# Integration in ein bestehendes Projekt

## Überblick

Der Client funktioniert eigenständig über die Kommandozeile. Zusätzlich lässt er
sich in drei Stufen in das Projekt einbinden – von "gar nicht" bis "vollständig".

Relevante Dateien:

- `manage-client/lib/client.php` – einziger Einstiegspunkt, lädt alles Weitere
- `manage-client/ui/panel.php` – vollständige Oberfläche
- `manage-client/ui/status-partial.php` – kleiner Statusblock
- `manage-client/bin/manage-client.php` – Kommandozeile für Cron

## Stufe 1: Standalone

Nichts zu tun. Der Client wird ausschließlich über die Kommandozeile bedient und
das Projekt weiß nichts von ihm. Nur der Ordner muss vorhanden und konfiguriert sein.

Diese Stufe genügt, wenn Updates und Backups von einer Person mit Shell-Zugang
gepflegt werden.

## Stufe 2: Oberfläche im Adminbereich

`ui/panel.php` ist eine fertige Seite. Sie erwartet, dass das Projekt seine
**eigene Anmeldung bereits geprüft hat**, bevor die Datei eingebunden wird.

Neue Datei `admin/manage.php` im Projekt:

```php
<?php

require_once __DIR__ . "/../config.php";
require_once __DIR__ . "/../includes/functions.php";

// Anmeldung des Projekts – hier steht, was das Projekt ohnehin verwendet.
if (empty($_SESSION["admin_logged_in"])) {
    header("Location: login.php");
    exit;
}

require __DIR__ . "/../manage-client/ui/panel.php";
```

Das Panel bringt eine eigene Prüfung auf `$_SESSION["admin_logged_in"]` mit, damit
ein direkter Aufruf nicht ungeschützt ist. Verwendet das Projekt ein anderes
Session-Flag, gibt es zwei Möglichkeiten:

1. den Guard in `ui/panel.php` anpassen (der Ordner wird ohnehin pro Projekt gepflegt), oder
2. vor dem Einbinden `define("MANAGE_PANEL_SKIP_AUTH_GUARD", true);` setzen, wenn die
   Anmeldung im aufrufenden Skript bereits sichergestellt ist.

Die zweite Variante deaktiviert **nur** die zusätzliche Prüfung des Panels. Wer sie
setzt, ohne vorher selbst zu prüfen, veröffentlicht Update- und Backup-Funktionen
im Internet.

### Statusblock auf einer bestehenden Seite

Für eine Einstellungsseite genügt oft der kleine Block:

```php
<?php
$manageStatusPanelUrl = "manage.php";
include __DIR__ . "/../manage-client/ui/status-partial.php";
?>
```

Er rendert nur ein Fragment, wirft nie eine Exception und zeigt Version,
Update-Verfügbarkeit, letztes Backup und offene Migrationen.

## Stufe 3: Funktionsaufrufe im Projekt

Alle Funktionen aus [04_FUNCTION_API](04_FUNCTION_API.md) können direkt aufgerufen
werden:

```php
require_once __DIR__ . "/manage-client/lib/client.php";

// z. B. auf dem Admin-Dashboard: automatisches Backup, wenn fällig
manageBackupCreateAutomaticIfDue();
```

Dieser Aufruf ist die Variante für Hosting ohne Cron: Er erstellt ein Backup, wenn
seit dem letzten automatischen Backup `MANAGE_BACKUP_AUTO_INTERVAL_SECONDS` vergangen
sind, und gibt sonst sofort `null` zurück. Ein Backup dauert je nach Datenmenge
mehrere Sekunden – deshalb gehört der Aufruf auf eine selten geladene Adminseite,
nicht auf jede Seite des Projekts.

## Cron

Cron ist der empfohlene Weg. Beispielzeilen liegen in
`examples/cron/manage-client.cron`:

```cron
# Backup, jede Nacht um 03:20 Uhr
20 3 * * * /usr/bin/php /pfad/zum/projekt/manage-client/bin/manage-client.php backup --trigger=cron --quiet

# Statusmeldung an den Manage-Server, stündlich
7 * * * * /usr/bin/php /pfad/zum/projekt/manage-client/bin/manage-client.php heartbeat --quiet

# Update-Prüfung, werktags um 08:00 Uhr (Exit 2 = Update verfügbar)
0 8 * * 1-5 /usr/bin/php /pfad/zum/projekt/manage-client/bin/manage-client.php check --quiet
```

`--quiet` unterdrückt die normale Ausgabe; Fehler gehen weiterhin auf STDERR und
werden von Cron per Mail zugestellt. Updates werden bewusst **nicht** automatisch
eingespielt: `update` bleibt eine bewusste Entscheidung.

## .gitignore des Projekts

Ins `.gitignore` des Projekts gehören:

```gitignore
manage-client/config.php
data/manage/
```

Der übrige Inhalt von `manage-client/` **soll** eingecheckt werden, damit er Teil
des Release-Pakets ist und mit ausgerollt wird.

## Verzeichnisse und Rechte

PHP braucht Schreibrechte auf:

- `data/manage/backups/` – lokale Archive
- `data/manage/work/` – Arbeitsverzeichnis für Updates (wird nach jedem Lauf geleert)
- `data/manage/updates/` – Sicherungskopien der überschriebenen Dateien
- den **gesamten Anwendungsstamm**, sofern Updates eingespielt werden sollen

Fehlen Schreibrechte im Anwendungsstamm, schlägt ein Update mittendrin fehl. Siehe
[09_TROUBLESHOOTING](09_TROUBLESHOOTING.md).

Diese Verzeichnisse dürfen nicht über das Web erreichbar sein. Bei Apache erledigt
das üblicherweise die `.htaccess` des Projekts; das mitgelieferte
`manage-client/.htaccess` schützt zusätzlich `config.php`, `lib/` und `bin/`.

## Weiter

- [03_CONFIG_REFERENCE](03_CONFIG_REFERENCE.md) – alle Konstanten
- [05_BACKUP_SOURCES](05_BACKUP_SOURCES.md) – was gesichert wird
- [06_UPDATE_PACKAGING](06_UPDATE_PACKAGING.md) – wie Release-Pakete gebaut werden