manager/client-docs/content/00_OVERVIEW.md

Overview

The Manage client brings two things into a standalone PHP project: a way to install new versions, and regular backups of operational data.

This is the published version of the client-package/ folder from the Manage repository: {{DOC_COUNT}} chapters and {{CODE_COUNT}} source files, each on its own page, plus the interface to the server as OpenAPI. Everything is read fresh from the repository on every request; what's here is the current state.

What the client does

Three operations, all through the same functions, whether they're triggered from the command line, from the bundled UI, or directly from the project.

Update. manageUpdateCheck() fetches the manifest from the server and compares versions. manageUpdateApply() downloads the package, checks size and SHA-256, extracts it into a working directory while checking every ZIP entry against path traversal, requires at least one sanity path in the archive, then copies file by file into the project and saves every overwritten file first into a timestamped folder. Protected paths are skipped. After that, the migrations from the package run, along with an optional callback.

Backup. manageBackupCreate() collects the configured sources — globs, directories, individual files, each with a target prefix in the archive —, optionally appends a MySQL dump, writes a ZIP, applies local retention, and uploads the archive to the Manage server as well as to optional extra targets (S3, SFTP, a custom endpoint). A lock file prevents concurrent runs. A failed upload does not invalidate the local archive.

Heartbeat. manageHeartbeatSend() reports version, PHP version, free disk space, pending migrations and the time of the last backup. The response includes the update information as a side effect.

Integrate, don't rebuild

The client is cut so it can be copied as a folder into a foreign project. It has no dependencies, no build step, and no assumptions about the target project beyond PHP. Rebuilding it costs time and loses details already solved here — checksums, protected paths, lock files, resuming after partial failure.

1. Take manage-client/ from the source part into the target project, paths and content unchanged.
2. Copy manage-client/config.sample.php to manage-client/config.php and set MANAGE_SERVER_URL, MANAGE_INSTANCE, MANAGE_TOKEN and MANAGE_BACKUP_SOURCES. The first three values come from the Manage server.
3. Check MANAGE_APP_ROOT, MANAGE_VERSION_FILE and MANAGE_VERSION_CONSTANT against the target project's actual layout. These are the only places where the client has to know anything about the project.
4. Extend MANAGE_UPDATE_PROTECTED_PATHS with anything an update must never overwrite, and MANAGE_UPDATE_SANITY_PATHS with a file present in every valid release.
5. Wire in one of the three entry points: the command line for cron, ui/panel.php for the admin area, or the function API for custom pages. See 02_INTEGRATION.md.
6. Check with php manage-client/bin/manage-client.php status.

Details in 01_QUICKSTART.md.

Writing your own client

Anyone who has to implement this in a different language will find the binding description of the interface in 08_PROTOCOL.md and the OpenAPI document. Three points decide whether the implementation is safe:

• Check SHA-256 and size of every package against the manifest and abort on mismatch, before anything is extracted.
• When extracting, check every entry against path traversal (.., absolute paths).
• When deploying, skip the protected paths — otherwise the first update overwrites the configuration and the operational data.

Limits

These points are missing deliberately. Anyone expecting them is building on a false assumption.

• No restore. Backups are created, transferred and made available for download, but never played back automatically. An update backs up the files it overwrites, but cannot bring them back.
• No automatic updates. The server offers; the instance decides.
• No package signing. The checksum and the package come from the same server; the safeguard is TLS plus the token.
• No maintenance page. Deployment overwrites files while the application is live.
• No backup before the update. That's deliberately a visible line in the project rather than something built in; see 04_FUNCTION_API.md.

Requirements

PHP 8.0 or newer, the zip extension for updates, write access to the project's data directory. No Composer, no build step, no external libraries.