# 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

```bash
# 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](docs/01_QUICKSTART.md).

## Contents

```text
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](docs/01_QUICKSTART.md) | from this folder to the first backup |
| [02_INTEGRATION](docs/02_INTEGRATION.md) | integration into an existing project, cron, permissions |
| [03_CONFIG_REFERENCE](docs/03_CONFIG_REFERENCE.md) | every constant with its default value and meaning |
| [04_FUNCTION_API](docs/04_FUNCTION_API.md) | the callable functions with return values |
| [05_BACKUP_SOURCES](docs/05_BACKUP_SOURCES.md) | what gets backed up, database dumps, extra targets |
| [06_UPDATE_PACKAGING](docs/06_UPDATE_PACKAGING.md) | how a release package must be built |
| [07_POST_UPDATE_HOOKS](docs/07_POST_UPDATE_HOOKS.md) | migrations and the project callback after an update |
| [08_PROTOCOL](docs/08_PROTOCOL.md) | the HTTP interface, for custom clients and debugging |
| [09_TROUBLESHOOTING](docs/09_TROUBLESHOOTING.md) | every error message with cause and fix |
| [10_SECURITY](docs/10_SECURITY.md) | 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:

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

Details: [docs/06_UPDATE_PACKAGING.md](docs/06_UPDATE_PACKAGING.md).

## Commands

```text
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.