# Integration Into an Existing Project

## Overview

The client works standalone from the command line. It can additionally be
wired into the project in three stages — from "not at all" to "fully".

Relevant files:

- `manage-client/lib/client.php` – the only entry point, loads everything else
- `manage-client/ui/panel.php` – the complete UI
- `manage-client/ui/status-partial.php` – a small status block
- `manage-client/bin/manage-client.php` – command line for cron

## Stage 1: standalone

Nothing to do. The client is operated exclusively from the command line and
the project knows nothing about it. Only the folder needs to exist and be
configured.

This stage is enough when updates and backups are maintained by one person
with shell access.

## Stage 2: UI in the admin area

`ui/panel.php` is a ready-made page. It expects the project to have
**already checked its own login** before the file is included.

New file `admin/manage.php` in the project:

```php
<?php

require_once __DIR__ . "/../config.php";
require_once __DIR__ . "/../includes/functions.php";

// The project's own login check - whatever the project already uses.
if (empty($_SESSION["admin_logged_in"])) {
    header("Location: login.php");
    exit;
}

require __DIR__ . "/../manage-client/ui/panel.php";
```

The panel brings its own check on `$_SESSION["admin_logged_in"]`, so a
direct call isn't left unprotected. If the project uses a different session
flag, there are two options:

1. adjust the guard in `ui/panel.php` (this folder is maintained per project
   anyway), or
2. set `define("MANAGE_PANEL_SKIP_AUTH_GUARD", true);` before including it,
   if the login is already guaranteed in the calling script.

The second option **only** disables the panel's extra check. Setting it
without checking the login yourself publishes update and backup functions
to the internet.

### Status block on an existing page

For a settings page, the small block is often enough:

```php
<?php
$manageStatusPanelUrl = "manage.php";
include __DIR__ . "/../manage-client/ui/status-partial.php";
?>
```

It renders only a fragment, never throws an exception, and shows version,
update availability, last backup and pending migrations.

## Stage 3: function calls in the project

All functions from [04_FUNCTION_API](04_FUNCTION_API.md) can be called
directly:

```php
require_once __DIR__ . "/manage-client/lib/client.php";

// e.g. on the admin dashboard: automatic backup when due
manageBackupCreateAutomaticIfDue();
```

This call is the option for hosting without cron: it creates a backup once
`MANAGE_BACKUP_AUTO_INTERVAL_SECONDS` has passed since the last automatic
backup, and otherwise returns `null` immediately. A backup takes several
seconds depending on the amount of data — so the call belongs on a rarely
loaded admin page, not on every page of the project.

## Cron

Cron is the recommended path. Example lines live in
`examples/cron/manage-client.cron`:

```cron
# Backup, every night at 03:20.
20 3 * * * /usr/bin/php /path/to/project/manage-client/bin/manage-client.php backup --trigger=cron --quiet

# Status report to the Manage server, hourly.
7 * * * * /usr/bin/php /path/to/project/manage-client/bin/manage-client.php heartbeat --quiet

# Update check, weekdays at 08:00 (exit 2 = update available).
0 8 * * 1-5 /usr/bin/php /path/to/project/manage-client/bin/manage-client.php check --quiet
```

`--quiet` suppresses normal output; errors still go to STDERR and are
delivered by cron via mail. Updates are deliberately **not** installed
automatically: `update` remains a deliberate decision.

## The project's .gitignore

The project's `.gitignore` should contain:

```gitignore
manage-client/config.php
data/manage/
```

The rest of `manage-client/` **should** be checked in, so it's part of the
release package and gets deployed along with it.

## Directories and permissions

PHP needs write access to:

- `data/manage/backups/` – local archives
- `data/manage/work/` – working directory for updates (cleared after every run)
- `data/manage/updates/` – copies of the files an update overwrote
- the **entire application root**, if updates are to be deployed

Without write access in the application root, an update fails partway
through. See [09_TROUBLESHOOTING](09_TROUBLESHOOTING.md).

These directories must not be reachable over the web. On Apache, the
project's own `.htaccess` usually handles that; the bundled
`manage-client/.htaccess` additionally protects `config.php`, `lib/` and
`bin/`.

## Next

- [03_CONFIG_REFERENCE](03_CONFIG_REFERENCE.md) – every constant
- [05_BACKUP_SOURCES](05_BACKUP_SOURCES.md) – what gets backed up
- [06_UPDATE_PACKAGING](06_UPDATE_PACKAGING.md) – how release packages are built