manager/client-package/README.md

Manage Client Package

Update and backup client for PHP projects, together with the complete documentation for integrating it. This folder is built so it can be handed over as a single ZIP: whoever receives it needs neither access to the Manage server's repository nor further explanation.

What this is

A PHP client that

• fetches, verifies and installs releases from a central Manage server,
• creates backups of operational data and uploads them there,
• reports the installation's status to the server.

The client runs standalone from the command line, brings a ready-made UI for the admin area, and exposes every function for direct calls from the project. All three paths call the same functions, so a given operation behaves identically no matter how it's triggered.

No dependencies: no Composer, no build step, no external libraries. PHP 8.0 or newer, ext-zip for updates, write access to the data directory.

In five minutes

# 1. Copy the folder into the project
cp -r manage-client /path/to/project/manage-client

# 2. Create an instance on the Manage server and copy the token shown once

# 3. Create the configuration
cd /path/to/project/manage-client
cp config.sample.php config.php
# Set MANAGE_SERVER_URL, MANAGE_INSTANCE, MANAGE_TOKEN and MANAGE_BACKUP_SOURCES

# 4. Check the connection
php bin/manage-client.php status

# 5. First backup
php bin/manage-client.php backup

Details: docs/01_QUICKSTART.md.

Contents

manage-client/            <- this folder gets copied into the project
  config.sample.php       template, becomes config.php
  lib/                    the library; client.php is the only entry point
  bin/manage-client.php   command line for cron and shell
  ui/panel.php            ready-made page for the admin area
  ui/status-partial.php   small status block for an existing page

docs/                     the documentation, see below
examples/                 working examples to copy from
scripts/                  build script for release packages, see below

Readable in the browser: open docs/index.php through any PHP server, for example php -S localhost:8080 -t docs. The files are also readable as plain Markdown.

Documentation

Document	Content
01_QUICKSTART	from this folder to the first backup
02_INTEGRATION	integration into an existing project, cron, permissions
03_CONFIG_REFERENCE	every constant with its default value and meaning
04_FUNCTION_API	the callable functions with return values
05_BACKUP_SOURCES	what gets backed up, database dumps, extra targets
06_UPDATE_PACKAGING	how a release package must be built
07_POST_UPDATE_HOOKS	migrations and the project callback after an update
08_PROTOCOL	the HTTP interface, for custom clients and debugging
09_TROUBLESHOOTING	every error message with cause and fix
10_SECURITY	token, permissions, checklist before going live

Recommended order for the first read: 01, 02, 05, 06. The rest is reference material.

Examples

File	Content
examples/flat-file-project/	project with JSON files, including an example migration
examples/mysql-project/	project with MySQL, database dump and an ALTER TABLE migration
examples/after-update.php	template for the post-update callback
examples/integration-snippet.php	the lines an existing project needs
examples/cron/manage-client.cron	ready-made crontab lines

Building release packages

scripts/create-release-zip.sh builds the ZIP from a project that gets uploaded to the Manage server as a release. It gets copied to scripts/ of the project, adjusted once at the top (product name, version file, exclusions), and then run from the project directory:

./scripts/create-release-zip.sh v1.3.0

Details: docs/06_UPDATE_PACKAGING.md.

Commands

php manage-client/bin/manage-client.php status
                                        check                      exit 2 = update available
                                        update [--force] [--yes] [--skip-hook]
                                        migrate [--dry-run]
                                        backup [--trigger=cron]
                                        heartbeat

Exit codes: 0 success, 1 error, 2 update available (check only). --quiet suppresses normal output; errors still go to STDERR.

What the client deliberately does not do

• No restore. Backups are created and transferred, but never played back. An update backs up the files it overwrites, but cannot bring them back. Both are deliberately manual work.
• No automatic updates. update is always a deliberate decision.
• No removal of deleted files. An update overlays what's there; a file missing from the new release stays behind. To make it disappear, that belongs in a migration.
• No maintenance mode. The application stays reachable while rolling out.

Customizing

This folder is maintained per project. Adjustments to ui/panel.php — for example to the login or the project's look — are expected and explicitly welcome. Changes inside lib/ should stay sparse, so a newer version of the client package can still be adopted.