manager/client-package

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

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

Inhalt

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	Von diesem Ordner zum ersten Backup
02_INTEGRATION	Einbindung in ein bestehendes Projekt, Cron, Rechte
03_CONFIG_REFERENCE	Jede Konstante mit Standardwert und Bedeutung
04_FUNCTION_API	Die aufrufbaren Funktionen mit Rückgabewerten
05_BACKUP_SOURCES	Was gesichert wird, Datenbank-Dump, zusätzliche Ziele
06_UPDATE_PACKAGING	Wie ein Release-Paket gebaut werden muss
07_POST_UPDATE_HOOKS	Migrationen und Projekt-Callback nach dem Update
08_PROTOCOL	Die HTTP-Schnittstelle, für eigene Clients und Debugging
09_TROUBLESHOOTING	Jede Fehlermeldung mit Ursache und Behebung
10_SECURITY	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:

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

Einzelheiten: docs/06_UPDATE_PACKAGING.md.

Befehle

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.