# Standalone PHP connector

The standalone collector runs on PHP CLI 7.4 or later and has no third-party dependencies. It works on Windows, Linux and macOS wherever PHP CLI and HTTPS are available. It sends a heartbeat to a SiteWatch dashboard you control; it does not instrument the PHP web process or prove that the application is healthy.

## Setup

1. Add the website in SiteWatch with backend reporting enabled, then save its one-time connector config file from the setup dialog.
2. Download `php-agent.php` from Connectors, and move both files to a private tools directory outside the website document root and source-control checkout.
3. Restrict access to the `.env` config file to the account that runs the collector. On Windows, download `protect-agent-config-windows.ps1` from Connectors and run `powershell.exe -NoProfile -File .\\protect-agent-config-windows.ps1 -ConfigPath 'C:\\private\\sitewatch-agent-ID.env'`. It replaces the file DACL with access for your current account and SYSTEM. If Task Scheduler uses a different account, add `-RunAsAccount 'COMPUTER\\sitewatch-runner'`; that account receives read-only access. Run the helper as the account that owns the config file. It refuses symlink/reparse-point files and parent directories. On Linux/macOS, use `chmod 600` and a private parent directory.
4. Run one report manually: `php /private/tools/php-agent.php --config-file /private/tools/sitewatch-agent-ID.env`. The path is an argument; the bearer token stays inside the protected file and the request header.
5. Schedule that command every five minutes using the host's task scheduler. Use a dedicated, unprivileged account that can read the config and `composer.lock`.

The dashboard config contains `SITEWATCH_URL`, `SITEWATCH_SITE_ID` and `SITEWATCH_TOKEN`. To collect project/framework inventory, add `SITEWATCH_PROJECT_ROOT="/path/to/project"` to that config. The agent reads only that project's `composer.lock`; it never executes Composer, project code or application files. It recognizes a bounded set of common frameworks. It does not report private Composer registry URLs, package source URLs, integrity hashes or arbitrary manifest fields.

Composer package names and versions stay out of reports unless you add `SITEWATCH_INCLUDE_COMPOSER_PACKAGES="true"`. This opt-in can disclose private package names to SiteWatch; if dependency advisory checks are enabled, normalized package identities may be sent to the advisory provider. Review that data flow before enabling it for private software. The collector caps `composer.lock` at 1 MiB, examines at most 2,000 package records and sends no more than 400 exact-version dependencies. Unsupported/dynamic versions and malformed records are omitted; empty or incomplete inventory is not proof that the project has no dependencies.

The request uses the configured HTTPS origin, refuses redirects, verifies TLS peer and hostname, sends no data in the URL, and bounds the SiteWatch response. Plain HTTP is accepted only for a loopback dashboard during same-machine development; use the exact configured dashboard origin in production so browser and connector requests reach the intended server. The report contains the PHP CLI version and OS family, recognized framework names/versions, and optionally exact Composer package identities. It does not inspect web-server PHP settings, database health, requests, pages, forms, logs, malware or source files. Use public checks and a read-only application health endpoint for those signals.

For a Windows Task Scheduler action, use the PHP executable, set **Add arguments** to `"C:\path\to\php-agent.php" --config-file "C:\private\sitewatch-agent-ID.env"`, and set **Start in** to the project directory when collecting Composer inventory. Configure a five-minute repetition and run as the restricted account that owns the config file. On Linux/macOS, configure the equivalent schedule in cron, systemd or launchd; keep the config path in the command and the token only in the protected config file.

Validation: CI runs PHP syntax checks and offline connector fixtures on Ubuntu, macOS, and Windows with PHP 7.4 and 8.4. These checks do not contact SiteWatch or a real provider. A real host heartbeat remains pending on this Windows development host.