sitetus / collector

v0.7.2 2026-10-13 15:42 UTC

Requires

• php: >=7.4

Requires (Dev)

• phpunit/phpunit: ^9.6

MIT

Published on Packagist.org on 2026-10-13 16:06 UTC

README

Read-only collector for the Sitetus monitoring panel: a single PHP file you place on your server so the panel can read a package inventory and health facts from inside the site, through signed requests the panel sends. It is optional: the panel works without it; the collector only adds inventory and inside-the-server health data.

The file is generated by the panel for each installation (public key, identifier and a random path baked in) and downloaded as a zip. The Laravel wrapper (sitetus/laravel-collector) installs the same core through Composer.

What this file will not do

A public commitment, enforced by the code and its tests:

• It never reads or transmits .env or configuration files. Level 2 reports a fixed list of flags and counts only: app.debug, app.env, session cookie flags, the app.url scheme, whether APP_KEY is set, the names of the mail / cache / queue / session drivers, the number of pending jobs and migrations, flags for the public/storage link, the Redis version string; from php.ini only flags and limits, never paths.
• Maintenance mode is read from the marker file only as on/off, for how long, and whether a bypass secret exists — never the secret or the file content.
• It never transmits file contents, logs included — only sizes, counts and ages. Optional modules add relative file names under the web root (at most 50 each), never content. The first 4 KB of .htaccess / .user.ini / web.config in the uploads directory are read locally and reported only as a class: enables PHP / protective / unknown. The bot-traffic module reports counts per bot identity from the access log — never an IP, an address, a referer or a User-Agent string.
• It never reads database records (only a connection attempt, its latency and the server version), collects no personal data, makes no outbound requests on its own, stores no secret on the server and writes nothing except its own nonce file.
• It never uses a request parameter as a path, command or include target.
• Modules you did not select are not in the file at all, and the panel cannot push code into it.
• Unsigned or invalid requests get an empty 404, exactly as if the file did not exist. After expires_at, or after 90 days without a valid request, it sleeps (404) until a new package is installed.
• The code is open source (MIT).

How it works

• The panel's package puts the file under a random path (public/<random>/index.php).
• The panel sends a signed request there a few times a day; the file verifies the signature with the embedded public key (Ed25519, or RSA-SHA256 where sodium is unavailable) and answers with a read-only JSON envelope.
• Every unsigned or invalid request gets a bodyless 404. No secret lives on your server: the public key and the installation identifier are not secrets.
• Panel requests come from fixed IPs: https://sitetus.com/ips.txt

Install (shared hosting included)

1. Download the zip from the panel: index.php plus an install note.
2. Upload index.php with FTP or the file manager into the random-named folder under your public/ (or web root) directory, as the package says.
3. Press "Verify connection" in the panel. That is all.

Optional one line (Laravel): to let the panel watch the scheduler and queue health, add the single line from the package to routes/console.php and deploy; without it those two checks show "no data" and nothing else is affected.

Uninstall: delete the file. The panel side can also revoke the collector with one click.

Composer wrapper (Laravel)

The same core is available as the sitetus/laravel-collector package (PHP ≥ 8.1): its service provider registers the pull route (/sitetus/<install-path>), writes the scheduler and queue heartbeats itself (no line to add), and lets you add developer-defined checks to the envelope with Sitetus::check('orders_last_24h', fn () => CheckOutcome::ok(42)) — numbers and booleans only, never text. The envelope is byte-for-byte the single-file one, except for collector.name.

Verification

Every envelope carries the SHA-256 of the installed file (collector.file_hash); the panel compares it with the fingerprint it recorded when it generated your package, and the source version is written at the top of the file. composer build prints the SHA-256 of the build it produces.

Requirements

PHP ≥ 7.4, zero dependencies. Without the sodium extension the panel generates an RSA-signed package. Works under strict disable_functions; what it cannot measure is reported as "no data".

Development

composer install
composer test          # PHPUnit
composer build         # produces dist/index.php, lints it and prints its SHA-256

Security reports: write to [e-mail]; please do not open a public issue. See SECURITY.md.

License

MIT — LICENSE.