Medowar f62663ef10 removed references to psa project #2		1 maand geleden
..
docs	f62663ef10 removed references to psa project #2	1 maand geleden
examples	90e0d37438 initial commit	1 maand geleden
manage-client	f62663ef10 removed references to psa project #2	1 maand geleden
README.md	90e0d37438 initial commit	1 maand geleden

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

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

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.

README.md