# Manage Client – Handbuch

Update- und Backup-Funktionalität für eigenständige PHP-Projekte: Dokumentation und
vollständiger Quellcode auf einer Seite.

Diese Seite ist die veröffentlichte Fassung des Ordners `client-package/` aus dem
Manage-Repository. Sie enthält **{{DOC_COUNT}} Dokumente** und **{{CODE_COUNT}} Quelldateien**,
jeweils vollständig und unverändert, dazu die OpenAPI-Spezifikation der
Server-Schnittstelle. Alles wird bei jedem Aufruf frisch aus dem Repository gelesen;
was hier steht, ist der aktuelle Stand.

| | |
|---|---|
| Diese Seite | <{{SELF_URL}}/> |
| Reiner Text für Agenten | <{{SELF_URL}}/llms.txt> |
| API-Referenz (Swagger UI) | <{{SELF_URL}}/api.php> |
| OpenAPI-Dokument | <{{SELF_URL}}/openapi.php> |
| Manage-Server | <{{BASE_URL}}/> |

## Hinweis für LLM-Agenten

Wenn Sie ein Agent sind und den Auftrag haben, Update- und Backup-Funktionalität in ein
Projekt einzubauen: Diese Seite ist die vollständige Vorlage. Sie brauchen keine weitere
Quelle.

**Empfohlener Weg – das Paket übernehmen, nicht nachbauen.** Der Client ist bewusst 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.

Vorgehen:

1. Legen Sie `manage-client/` im Zielprojekt an und übernehmen Sie alle Dateien aus
   Teil 3 dieses Dokuments, die mit `manage-client/` beginnen – Pfade und Inhalte
   unverändert.
2. Kopieren Sie `manage-client/config.sample.php` nach `manage-client/config.php` und
   setzen Sie `MANAGE_SERVER_URL`, `MANAGE_INSTANCE`, `MANAGE_TOKEN` sowie
   `MANAGE_BACKUP_SOURCES`. Die Werte für die ersten drei kommen aus dem Manage-Server;
   fragen Sie danach, statt sie zu erfinden.
3. Prüfen Sie `MANAGE_APP_ROOT`, `MANAGE_VERSION_FILE` und `MANAGE_VERSION_CONSTANT`
   gegen den tatsächlichen Aufbau des Zielprojekts. Das sind die einzigen Stellen, an
   denen der Client etwas über das Projekt wissen muss.
4. Ergänzen Sie `MANAGE_UPDATE_PROTECTED_PATHS` um alles, was ein Update niemals
   überschreiben darf, und `MANAGE_UPDATE_SANITY_PATHS` um eine Datei, die in jedem
   gültigen Release vorkommt.
5. Binden Sie einen der drei Einstiegspunkte ein: Kommandozeile für Cron, `ui/panel.php`
   für den Adminbereich, oder die Funktions-API für eigene Seiten. Siehe das Kapitel
   *Integration*.
6. Prüfen Sie mit `php manage-client/bin/manage-client.php status`.

**Wenn Sie stattdessen neu implementieren müssen** – andere Sprache, anderes Framework –
ist das Kapitel *Protokoll* zusammen mit Teil 2 die verbindliche Beschreibung der
Schnittstelle. Halten Sie sich an drei Punkte, sonst ist die Implementierung unsicher:
SHA-256 und Größe jedes Pakets gegen das Manifest prüfen und bei Abweichung abbrechen;
beim Entpacken jeden Eintrag gegen Pfadausbruch prüfen; geschützte Pfade beim Ausrollen
auslassen.

**Was Sie nicht tun sollten:** die Konfigurationsdatei mit einem erfundenen Token
ausliefern, das Backup vor dem Update automatisch einbauen (das ist bewusst eine
sichtbare Zeile im Projekt), oder eine Wiederherstellungsfunktion versprechen – es gibt
keine, siehe unten.

## 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.

## 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.

## 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.

## Aufbau dieses Dokuments

**Teil 1** ist die Dokumentation des Pakets in Lesereihenfolge, beginnend mit dem
README und dem Quickstart. **Teil 2** beschreibt die HTTP-Schnittstelle zum
Manage-Server und enthält die vollständige OpenAPI-Spezifikation. **Teil 3** ist der
gesamte Quellcode. Am Ende steht eine Dateiübersicht.

Querverweise zwischen den Kapiteln zeigen innerhalb dieser Seite auf den jeweiligen
Abschnitt.