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

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.