manager/client-docs/content/00_UEBERBLICK.md

Ü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.
6. Mit php manage-client/bin/manage-client.php status prüfen.

Ausführlich in 01_QUICKSTART.md.

Einen eigenen Client schreiben

Wer in einer anderen Sprache implementieren muss, findet in 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.

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.