# Überblick

Der Manage-Client bringt zwei Dinge in ein eigenständiges PHP-Projekt: eine Möglichkeit,
neue Versionen einzuspielen, und regelmäßige Sicherungen der Betriebsdaten.

Dies ist die veröffentlichte Fassung des Ordners `client-package/` aus dem
Manage-Repository: {{DOC_COUNT}} Kapitel und {{CODE_COUNT}} Quelldateien, jede auf einer
eigenen Seite, dazu die Schnittstelle zum Server als OpenAPI. Alles wird bei jedem Aufruf
frisch aus dem Repository gelesen; was hier steht, ist der aktuelle Stand.

## Was der Client tut

Drei Vorgänge, alle über dieselben Funktionen, egal ob sie aus der Kommandozeile, aus der
mitgelieferten Oberfläche oder direkt aus dem Projekt ausgelöst werden.

**Update.** `manageUpdateCheck()` holt das Manifest vom Server und vergleicht die
Versionen. `manageUpdateApply()` lädt das Paket, prüft Größe und SHA-256, entpackt es in
ein Arbeitsverzeichnis, prüft dabei jeden ZIP-Eintrag gegen Pfadausbruch, verlangt
mindestens einen Sanity-Pfad im Archiv, kopiert dann Datei für Datei in das Projekt und
legt jede überschriebene Datei vorher in einem Zeitstempel-Ordner ab. Geschützte Pfade
werden übersprungen. Danach laufen die Migrationen aus dem Paket und ein optionaler
Callback.

**Backup.** `manageBackupCreate()` sammelt die konfigurierten Quellen – Globs,
Verzeichnisse, Einzeldateien, jeweils mit Zielpräfix im Archiv –, hängt optional einen
MySQL-Dump an, schreibt ein ZIP, wendet die lokale Aufbewahrung an und lädt das Archiv
zum Manage-Server sowie zu optionalen Zusatzzielen (S3, SFTP, eigener Endpunkt). Eine
Sperrdatei verhindert gleichzeitige Läufe. Ein fehlgeschlagener Upload macht das lokale
Archiv nicht ungültig.

**Heartbeat.** `manageHeartbeatSend()` meldet Version, PHP-Version, freien Speicher,
offene Migrationen und den Zeitpunkt des letzten Backups. Die Antwort enthält nebenbei
die Update-Information.

## Einbinden statt nachbauen

Der Client ist so geschnitten, dass er als Ordner in ein fremdes Projekt kopiert wird. Er
hat keine Abhängigkeiten, keinen Build-Schritt und keine Annahmen über das Zielprojekt
außer PHP. Nachbauen kostet Zeit und verliert Details, die hier bereits gelöst sind –
Prüfsummen, geschützte Pfade, Sperrdateien, Wiederanlauf nach Teilfehlern.

1. `manage-client/` aus dem Quellcode-Teil in das Zielprojekt übernehmen, Pfade und
   Inhalte unverändert.
2. `manage-client/config.sample.php` nach `manage-client/config.php` kopieren und
   `MANAGE_SERVER_URL`, `MANAGE_INSTANCE`, `MANAGE_TOKEN` sowie `MANAGE_BACKUP_SOURCES`
   setzen. Die ersten drei Werte kommen aus dem Manage-Server.
3. `MANAGE_APP_ROOT`, `MANAGE_VERSION_FILE` und `MANAGE_VERSION_CONSTANT` gegen den
   tatsächlichen Aufbau des Zielprojekts prüfen. Das sind die einzigen Stellen, an denen
   der Client etwas über das Projekt wissen muss.
4. `MANAGE_UPDATE_PROTECTED_PATHS` um alles ergänzen, was ein Update niemals überschreiben
   darf, und `MANAGE_UPDATE_SANITY_PATHS` um eine Datei, die in jedem gültigen Release
   vorkommt.
5. Einen der drei Einstiegspunkte einbinden: Kommandozeile für Cron, `ui/panel.php` für
   den Adminbereich, oder die Funktions-API für eigene Seiten. Siehe
   [02_INTEGRATION.md](02_INTEGRATION.md).
6. Mit `php manage-client/bin/manage-client.php status` prüfen.

Ausführlich in [01_QUICKSTART.md](01_QUICKSTART.md).

## Einen eigenen Client schreiben

Wer in einer anderen Sprache implementieren muss, findet in
[08_PROTOCOL.md](08_PROTOCOL.md) und im OpenAPI-Dokument die verbindliche Beschreibung
der Schnittstelle. Drei Punkte entscheiden darüber, ob die Implementierung sicher ist:

- SHA-256 **und** Größe jedes Pakets gegen das Manifest prüfen und bei Abweichung
  abbrechen, bevor irgendetwas entpackt wird.
- Beim Entpacken jeden Eintrag gegen Pfadausbruch prüfen (`..`, absolute Pfade).
- Beim Ausrollen die geschützten Pfade auslassen, sonst überschreibt das erste Update die
  Konfiguration und die Betriebsdaten.

## Grenzen

Diese Punkte fehlen bewusst. Wer sie erwartet, baut auf einer falschen Annahme auf.

- **Keine Wiederherstellung.** Backups werden erstellt, übertragen und zum Download
  bereitgestellt, aber nie automatisch zurückgespielt. Ein Update sichert die
  überschriebenen Dateien, kann sie aber nicht zurückholen.
- **Keine automatischen Updates.** Der Server bietet an, die Instanz entscheidet.
- **Keine Signatur der Pakete.** Prüfsumme und Paket kommen vom selben Server; die
  Absicherung ist TLS plus Token.
- **Keine Wartungsseite.** Das Ausrollen überschreibt Dateien im laufenden Betrieb.
- **Kein Backup vor dem Update.** Das ist bewusst eine sichtbare Zeile im Projekt und
  nicht eingebaut, siehe [04_FUNCTION_API.md](04_FUNCTION_API.md).

## Voraussetzungen

PHP 8.0 oder neuer, die Erweiterung `zip` für Updates, Schreibrechte auf dem
Datenverzeichnis des Projekts. Kein Composer, kein Build-Schritt, keine externen
Bibliotheken.