Download the PHP package mindtwo/base-monitoring without Composer

mindtwo/base-monitoring

The framework-agnostic collecting core of the mindtwo monitoring suite. It safely gathers infrastructure, package and security-audit data from any PHP environment and ships it as a signed, versioned JSON snapshot — either pushed to the central monitoring endpoint or served through a plugin's pull endpoint.

Framework plugins build on this core:

What it collects

Detected software is normalized to a technology slug pinned from endoflife.date, so the central dashboard can match versions against end-of-life data. Unknown software degrades to a slug derived from the package or org/repo name — resolution is always offline.

Safety guarantees

The core is built to run on any environment without ever breaking the host application:

• Per-collector fault isolation — every collector runs inside its own guard. A throwing collector becomes a failed metric, a missing binary an unsupported metric. One bad collector can never abort the snapshot.
• No shell interpolation — commands run as argv arrays through a ProcessRunner (symfony/process when installed, a dependency-free proc_open runner otherwise). Every run is timeout-bounded and degrades gracefully where process functions are disabled.
• Binary discovery without shelling out — the ExecutableFinder scans PATH plus common sbin directories in pure PHP.
• Zero runtime dependencies — PHP >= 8.0 and ext-json are all it needs.

Installation

Quick start

Pushing to the central endpoint

Custom collectors

A collector is one unit of data collection. Implement the contract (or extend AbstractCollector), return a CollectionResult, register it:

Collectors with prerequisites override unsupportedReason() instead of supported(). The reason travels with the metric as its error, so an unsupported status is diagnosable from the dashboard instead of requiring shell access to the monitored machine:

AbstractCollector::supported() derives from it (unsupportedReason() === null). Overriding supported() directly still works — the metric is then simply reported without a reason.

Audits without a composer binary

composer_audit needs only a readable composer.lock. Where a composer binary exists it runs composer audit; otherwise (and when the binary fails) it queries the same Packagist advisory API the binary uses, filters the advisories against the versions in composer.lock, and reads abandoned packages from the lock file. source on the metric says which route produced the data (composer or packagist-api). Advisories whose affected-version range cannot be evaluated are kept and flagged with version_uncertain rather than dropped.

The fallback sends package names only, to packagist.org — the same egress Composer itself performs. To keep the collector strictly offline, hand it a NullAdvisoryProvider:

The snapshot payload

metrics is an open map — each collector owns the shape under its key, so adding a collector adds a key and never requires a schema migration. Empty custom_data serializes as {}.

Every metric carries a status: ok, warning, failed, skipped or unsupported.

Authentication: signed requests (v1)

Authentication uses a project key + secret pair. The secret never travels on the wire — requests carry an HMAC signature instead, with a timestamp baked into the signed string for replay protection:

• payload is the raw request body (the exact JSON bytes for a push, the empty string for a body-less pull request).
• Verifiers reject timestamps outside a tolerance window (default 300 seconds) and compare in constant time (hash_equals).

Architecture

Every variable behavior is a contract in Mindtwo\Monitoring\Contracts with a default implementation — plugins extend, never modify:

Plugins additionally reuse Http\PullRequestHandler (the complete pull-endpoint guard chain), Support\FixedWindowRateLimiter, Support\IpMatcher and Support\DatabaseVersion, so security-relevant behavior is implemented and tested exactly once. Every metric carries a duration_ms so slow collectors are visible centrally.

Technology slug registry

The slug list is pinned in code (Technology\Slugs) for offline, deterministic resolution. Refresh it from the endoflife.date release data:

Review the diff, commit, release. Aliases for differing detector output live in Technology\Aliases and are extensible via the resolver constructor.

Development

PHP 8.0 compatibility is enforced statically (phpVersion: 80000 in phpstan.neon.dist).

Security

If you discover a security issue, please email [email protected] instead of opening a public issue.

License

The MIT License (MIT). See LICENSE.md.