# Manage Client-Paket

Update- und Backup-Client für PHP-Projekte, zusammen mit der vollständigen
Dokumentation zur Einbindung. Dieser Ordner ist so gebaut, dass er als einzelnes
ZIP weitergegeben werden kann: Wer ihn erhält, braucht weder Zugriff auf das
Repository des Manage-Servers noch weitere Erklärungen.

## Was das ist

Ein PHP-Client, der

- Releases von einem zentralen Manage-Server holt, prüft und einspielt,
- Backups der Betriebsdaten erstellt und dorthin hochlädt,
- den Status der Installation an den Server meldet.

Der Client läuft eigenständig über die Kommandozeile, bringt eine fertige
Oberfläche für den Adminbereich mit und stellt alle Funktionen zum direkten
Aufruf aus dem Projekt bereit. Alle drei Wege rufen dieselben Funktionen auf, ein
Vorgang verhält sich also überall gleich.

Keine Abhängigkeiten: kein Composer, kein Build-Schritt, keine externen
Bibliotheken. PHP 8.0 oder neuer, `ext-zip` für Updates, Schreibrechte auf dem
Datenverzeichnis.

## In fünf Minuten

```bash
# 1. Ordner ins Projekt kopieren
cp -r manage-client /pfad/zum/projekt/manage-client

# 2. Instanz im Manage-Server anlegen und das einmalig angezeigte Token kopieren

# 3. Konfiguration anlegen
cd /pfad/zum/projekt/manage-client
cp config.sample.php config.php
# MANAGE_SERVER_URL, MANAGE_INSTANCE, MANAGE_TOKEN und MANAGE_BACKUP_SOURCES setzen

# 4. Verbindung prüfen
php bin/manage-client.php status

# 5. Erstes Backup
php bin/manage-client.php backup
```

Ausführlich: [docs/01_QUICKSTART.md](docs/01_QUICKSTART.md).

## Inhalt

```text
manage-client/            <- dieser Ordner wird ins Projekt kopiert
  config.sample.php       Vorlage, wird zu config.php
  lib/                    die Bibliothek; client.php ist der einzige Einstiegspunkt
  bin/manage-client.php   Kommandozeile für Cron und Shell
  ui/panel.php            fertige Seite für den Adminbereich
  ui/status-partial.php   kleiner Statusblock für eine bestehende Seite

docs/                     die Dokumentation, siehe unten
examples/                 lauffähige Beispiele zum Abschreiben
scripts/                  Build-Skript für Release-Pakete, siehe unten
```

Im Browser lesbar: `docs/index.php` über einen beliebigen PHP-Server öffnen, zum
Beispiel `php -S localhost:8080 -t docs`. Die Dateien sind auch als reines
Markdown lesbar.

## Dokumentation

| Dokument | Inhalt |
|---|---|
| [01_QUICKSTART](docs/01_QUICKSTART.md) | Von diesem Ordner zum ersten Backup |
| [02_INTEGRATION](docs/02_INTEGRATION.md) | Einbindung in ein bestehendes Projekt, Cron, Rechte |
| [03_CONFIG_REFERENCE](docs/03_CONFIG_REFERENCE.md) | Jede Konstante mit Standardwert und Bedeutung |
| [04_FUNCTION_API](docs/04_FUNCTION_API.md) | Die aufrufbaren Funktionen mit Rückgabewerten |
| [05_BACKUP_SOURCES](docs/05_BACKUP_SOURCES.md) | Was gesichert wird, Datenbank-Dump, zusätzliche Ziele |
| [06_UPDATE_PACKAGING](docs/06_UPDATE_PACKAGING.md) | Wie ein Release-Paket gebaut werden muss |
| [07_POST_UPDATE_HOOKS](docs/07_POST_UPDATE_HOOKS.md) | Migrationen und Projekt-Callback nach dem Update |
| [08_PROTOCOL](docs/08_PROTOCOL.md) | Die HTTP-Schnittstelle, für eigene Clients und Debugging |
| [09_TROUBLESHOOTING](docs/09_TROUBLESHOOTING.md) | Jede Fehlermeldung mit Ursache und Behebung |
| [10_SECURITY](docs/10_SECURITY.md) | Token, Berechtigungen, Checkliste vor dem Produktivgang |

Empfohlene Reihenfolge beim ersten Mal: 01, 02, 05, 06. Der Rest ist Nachschlagewerk.

## Beispiele

| Datei | Inhalt |
|---|---|
| `examples/flat-file-project/` | Projekt mit JSON-Dateien, inklusive Beispielmigration |
| `examples/mysql-project/` | Projekt mit MySQL, Datenbank-Dump und `ALTER TABLE`-Migration |
| `examples/after-update.php` | Vorlage für den Post-Update-Callback |
| `examples/integration-snippet.php` | Die Zeilen, die ein bestehendes Projekt braucht |
| `examples/cron/manage-client.cron` | Fertige Crontab-Zeilen |

## Release-Pakete bauen

`scripts/create-release-zip.sh` baut aus einem Projekt das ZIP, das im
Manage-Server als Release hochgeladen wird. Es wird nach `scripts/` des Projekts
kopiert, am Kopf einmal angepasst (Produktname, Versionsdatei, Ausschlüsse) und
dann im Projektverzeichnis aufgerufen:

```bash
./scripts/create-release-zip.sh v1.3.0
```

Einzelheiten: [docs/06_UPDATE_PACKAGING.md](docs/06_UPDATE_PACKAGING.md).

## Befehle

```text
php manage-client/bin/manage-client.php status
                                        check                      Exit 2 = Update verfügbar
                                        update [--force] [--yes] [--skip-hook]
                                        migrate [--dry-run]
                                        backup [--trigger=cron]
                                        heartbeat
```

Exit-Codes: `0` Erfolg, `1` Fehler, `2` Update verfügbar (nur bei `check`).
`--quiet` unterdrückt die normale Ausgabe, Fehler gehen weiterhin auf STDERR.

## Was der Client bewusst nicht tut

- **Keine Wiederherstellung.** Backups werden erstellt und übertragen, aber nie
  zurückgespielt. Ein Update sichert die überschriebenen Dateien, kann sie aber
  nicht zurückholen. Beides ist bewusst Handarbeit.
- **Keine automatischen Updates.** `update` ist immer eine bewusste Entscheidung.
- **Kein Entfernen gelöschter Dateien.** Ein Update überlagert den Bestand; was im
  neuen Release fehlt, bleibt liegen. Soll es verschwinden, gehört das in eine
  Migration.
- **Kein Wartungsmodus.** Die Anwendung bleibt während des Ausrollens erreichbar.

## Anpassen

Der Ordner wird pro Projekt gepflegt. Anpassungen an `ui/panel.php` – etwa an die
Anmeldung oder das Aussehen des Projekts – sind vorgesehen und ausdrücklich
erwünscht. Änderungen in `lib/` sollten sparsam bleiben, damit eine neuere Fassung
des Client-Pakets noch übernommen werden kann.