manager/client-package/docs/03_CONFIG_REFERENCE.md

Configuration Reference

Overview

All constants live in manage-client/config.php, copied from manage-client/config.sample.php. Every constant has a default in manage-client/lib/client.php; a minimal config.php only needs the three connection values plus MANAGE_BACKUP_SOURCES.

Constants are set with define(), not as an array. If a constant is already defined by the project, the project's value wins.

Connection

Constant	Default	Meaning
MANAGE_SERVER_URL	""	base URL of the Manage server, without /api and without a trailing slash
MANAGE_INSTANCE	""	instance id, as created on the server
MANAGE_TOKEN	""	the instance's secret token, shown once when created
MANAGE_HTTP_TIMEOUT	15	seconds for manifest and heartbeat
MANAGE_HTTP_TIMEOUT_LONG	300	seconds for package download and backup upload

If any of the first three values is missing, every function that contacts the server reports a configuration error. Local backups still work as long as MANAGE_BACKUP_UPLOAD is false.

Application layout

Constant	Default	Meaning
MANAGE_APP_ROOT	parent directory of manage-client/	root of the application. Update target, base of every relative backup path
MANAGE_VERSION_FILE	MANAGE_APP_ROOT . "/VERSION"	file holding the installed version
MANAGE_VERSION_CONSTANT	null	name of the constant in that file, or null for a plain text file
MANAGE_WORK_DIR	data/manage/work/	working directory for updates, cleared after every run
MANAGE_UPDATE_BACKUP_DIR	data/manage/updates/	copies of the files an update overwrote
MANAGE_BACKUP_DIR	data/manage/backups/	local backup archives
MANAGE_LOG_FILE	data/manage/manage-client.log	the client's JSONL log

Version file

Two variants are supported.

PHP file with a constant:

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

Plain text file that only contains v1.2.3:

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

With the constant variant, the version is read from the file with a regular expression, and the file is not executed. That way reading it still works even when the constant is already defined in the running process with the old value — for example right after an update.

The version itself is never written by the client: it's part of the release package and changes as a side effect of copying files.

Update

Constant	Default	Meaning
MANAGE_UPDATE_PROTECTED_PATHS	["config.php", "data/", ".git/", "manage-client/config.php"]	paths that are never overwritten
MANAGE_UPDATE_SANITY_PATHS	["index.php"]	the package must contain at least one of these paths
MANAGE_UPDATE_POST_HOOK	null	callback after a successful update
MANAGE_MIGRATIONS_DIR	MANAGE_APP_ROOT . "/migrations"	directory with migration scripts, null disables them
MANAGE_MIGRATIONS_STATE	data/manage/migrations.json	which migrations have already run

Paths in MANAGE_UPDATE_PROTECTED_PATHS are relative to MANAGE_APP_ROOT. An entry with a trailing slash protects the directory and its contents; without a slash, the exact path is protected, but a directory is likewise protected with its contents. config.php and the data directory always belong here.

MANAGE_UPDATE_SANITY_PATHS prevents a completely unrelated ZIP from being copied over the application. The value should name a file or directory that every release contains.

The hook and migrations are described in 07_POST_UPDATE_HOOKS.

Backup

Constant	Default	Meaning
MANAGE_BACKUP_SOURCES	[["as" => "data", "glob" => "data/*.json"]]	what goes into the archive
MANAGE_BACKUP_DATABASE	null	optional MySQL dump
MANAGE_BACKUP_LOCAL_RETENTION	4	local archives kept. Minimum 1
MANAGE_BACKUP_AUTO_INTERVAL_SECONDS	604800	interval for manageBackupCreateAutomaticIfDue(), 0 disables it
MANAGE_BACKUP_COMPRESS	true	compress entries in the ZIP (deflate)
MANAGE_BACKUP_UPLOAD	true	send every new backup to the Manage server
MANAGE_BACKUP_REMOTE_TARGETS	[]	extra targets: s3, sftp, custom

Layout of sources and targets: 05_BACKUP_SOURCES.

MANAGE_BACKUP_COMPRESS needs zlib, which is present in PHP by default. If it's missing, the client writes without compression instead of aborting. For archives that are mostly JPEGs, compression gains almost nothing; for SQL dumps it gains a lot.

Local retention is independent of retention on the Manage server. On the server it's maintained centrally in the server settings, usually considerably higher than locally.

Interplay with the project

If the project already defines a constant itself, that value wins, because the client's config.php loads before the defaults, and every default is set with if (!defined(...)). This lets a project configure its paths centrally and have the client pick them up.

Next

• 04_FUNCTION_API – the callable functions
• 09_TROUBLESHOOTING – error messages and their causes