# Konfigurationsreferenz

## Überblick

Alle Konstanten stehen in `manage-client/config.php`, kopiert aus
`manage-client/config.sample.php`. Jede Konstante hat einen Standardwert in
`manage-client/lib/client.php`; eine minimale `config.php` braucht nur die drei
Verbindungswerte und `MANAGE_BACKUP_SOURCES`.

Konstanten werden mit `define()` gesetzt, nicht als Array. Wird eine Konstante
bereits vom Projekt definiert, gewinnt der Wert des Projekts.

## Verbindung

| Konstante | Standard | Bedeutung |
|---|---|---|
| `MANAGE_SERVER_URL` | `""` | Basis-URL des Manage-Servers, ohne `/api` und ohne Schrägstrich am Ende |
| `MANAGE_INSTANCE` | `""` | Kennung der Instanz, wie auf dem Server angelegt |
| `MANAGE_TOKEN` | `""` | Geheimes Token der Instanz, einmalig beim Anlegen angezeigt |
| `MANAGE_HTTP_TIMEOUT` | `15` | Sekunden für Manifest und Heartbeat |
| `MANAGE_HTTP_TIMEOUT_LONG` | `300` | Sekunden für Paket-Download und Backup-Upload |

Fehlt einer der ersten drei Werte, melden alle Funktionen mit Serverkontakt einen
Konfigurationsfehler. Lokale Backups funktionieren trotzdem, sofern
`MANAGE_BACKUP_UPLOAD` auf `false` steht.

## Anwendungslayout

| Konstante | Standard | Bedeutung |
|---|---|---|
| `MANAGE_APP_ROOT` | Elternverzeichnis von `manage-client/` | Wurzel der Anwendung. Ziel des Updates, Basis aller relativen Backup-Pfade |
| `MANAGE_VERSION_FILE` | `MANAGE_APP_ROOT . "/VERSION"` | Datei mit der installierten Version |
| `MANAGE_VERSION_CONSTANT` | `null` | Name der Konstante in dieser Datei, oder `null` für eine reine Textdatei |
| `MANAGE_WORK_DIR` | `data/manage/work/` | Arbeitsverzeichnis für Updates, wird nach jedem Lauf geleert |
| `MANAGE_UPDATE_BACKUP_DIR` | `data/manage/updates/` | Sicherungskopien der überschriebenen Dateien |
| `MANAGE_BACKUP_DIR` | `data/manage/backups/` | Lokale Backup-Archive |
| `MANAGE_LOG_FILE` | `data/manage/manage-client.log` | JSONL-Protokoll des Clients |

### Versionsdatei

Zwei Varianten werden unterstützt.

PHP-Datei mit Konstante (wie im PSA-Bestellsystem):

```php
define("MANAGE_VERSION_FILE", MANAGE_APP_ROOT . "/includes/version.php");
define("MANAGE_VERSION_CONSTANT", "APP_VERSION");
```

Reine Textdatei, die nur `v1.2.3` enthält:

```php
define("MANAGE_VERSION_FILE", MANAGE_APP_ROOT . "/VERSION");
define("MANAGE_VERSION_CONSTANT", null);
```

Die Version wird bei der Variante mit Konstante per regulärem Ausdruck aus der Datei
gelesen und die Datei dabei **nicht** ausgeführt. Damit funktioniert das Auslesen
auch dann, wenn die Konstante im laufenden Prozess bereits mit dem alten Wert
definiert ist – zum Beispiel unmittelbar nach einem Update.

Die Version selbst wird nie vom Client geschrieben: Sie ist Teil des Release-Pakets
und ändert sich als Nebeneffekt des Dateikopierens.

## Update

| Konstante | Standard | Bedeutung |
|---|---|---|
| `MANAGE_UPDATE_PROTECTED_PATHS` | `["config.php", "data/", ".git/", "manage-client/config.php"]` | Pfade, die nie überschrieben werden |
| `MANAGE_UPDATE_SANITY_PATHS` | `["index.php"]` | Das Paket muss mindestens einen dieser Pfade enthalten |
| `MANAGE_UPDATE_POST_HOOK` | `null` | Callback nach erfolgreichem Update |
| `MANAGE_MIGRATIONS_DIR` | `MANAGE_APP_ROOT . "/migrations"` | Verzeichnis mit Migrationsskripten, `null` deaktiviert sie |
| `MANAGE_MIGRATIONS_STATE` | `data/manage/migrations.json` | Welche Migrationen bereits gelaufen sind |

Pfade in `MANAGE_UPDATE_PROTECTED_PATHS` sind relativ zu `MANAGE_APP_ROOT`. Ein
Eintrag mit Schrägstrich am Ende schützt das Verzeichnis samt Inhalt; ohne
Schrägstrich wird der genaue Pfad geschützt, ein Verzeichnis aber ebenfalls
mitsamt Inhalt. `config.php` und das Datenverzeichnis gehören immer dazu.

`MANAGE_UPDATE_SANITY_PATHS` verhindert, dass ein völlig fremdes ZIP über die
Anwendung kopiert wird. Der Wert sollte eine Datei oder ein Verzeichnis benennen,
das in jedem Release enthalten ist.

Hook und Migrationen sind in [07_POST_UPDATE_HOOKS](07_POST_UPDATE_HOOKS.md)
beschrieben.

## Backup

| Konstante | Standard | Bedeutung |
|---|---|---|
| `MANAGE_BACKUP_SOURCES` | `[["as" => "data", "glob" => "data/*.json"]]` | Was ins Archiv kommt |
| `MANAGE_BACKUP_DATABASE` | `null` | Optionaler MySQL-Dump |
| `MANAGE_BACKUP_LOCAL_RETENTION` | `4` | Lokale Archive, die behalten werden. Minimum 1 |
| `MANAGE_BACKUP_AUTO_INTERVAL_SECONDS` | `604800` | Intervall für `manageBackupCreateAutomaticIfDue()`, `0` deaktiviert |
| `MANAGE_BACKUP_COMPRESS` | `true` | Einträge im ZIP komprimieren (Deflate) |
| `MANAGE_BACKUP_UPLOAD` | `true` | Jedes neue Backup an den Manage-Server senden |
| `MANAGE_BACKUP_REMOTE_TARGETS` | `[]` | Zusätzliche Ziele: `s3`, `sftp`, `custom` |

Aufbau von Quellen und Zielen: [05_BACKUP_SOURCES](05_BACKUP_SOURCES.md).

`MANAGE_BACKUP_COMPRESS` benötigt zlib, das in PHP standardmäßig vorhanden ist.
Fehlt es, wird ohne Kompression geschrieben statt abzubrechen. Für Archive, die
überwiegend aus JPEGs bestehen, bringt Kompression fast nichts; für SQL-Dumps sehr viel.

Die lokale Aufbewahrung ist unabhängig von der Aufbewahrung auf dem Manage-Server.
Auf dem Server wird sie zentral in den Servereinstellungen gepflegt, üblicherweise
deutlich höher als lokal.

## Zusammenspiel mit dem Projekt

Definiert das Projekt eine Konstante bereits selbst, gewinnt sie, weil `config.php`
des Clients vor den Standardwerten geladen wird und alle Standardwerte mit
`if (!defined(...))` gesetzt sind. So kann ein Projekt seine Pfade zentral
konfigurieren und der Client sie übernehmen.

## Weiter

- [04_FUNCTION_API](04_FUNCTION_API.md) – die aufrufbaren Funktionen
- [09_TROUBLESHOOTING](09_TROUBLESHOOTING.md) – Fehlermeldungen und Ursachen