build-gaia/php-collector

Production-safe PHP and Laravel telemetry collector for Chronos

dev-main 2026-08-13 12:14 UTC

Requires

• php: >=8.1

Suggests

• laravel/framework: Required for automatic Laravel HTTP instrumentation
• symfony/framework-bundle: Required for Symfony HTTP instrumentation

Apache-2.0

Published on Packagist.org on 2026-08-13 12:58 UTC

README

Composer package: build-gaia/php-collector.

The PHP Collector provides production-safe selection, bounded framework timeline records, source and runtime identity, signed policy enforcement, local buffering, replay inputs, and opt-in diagnostic workflows for Chronos.

The package is dependency-free and requires PHP 8.2 or later. It remains inert until an application supplies an enabled recording policy. It does not make a blocking network call from an observed request or define cross-service schemas.

Structure

Production code uses the Chronos\PhpCollector namespace. Every class, enum, interface, and exception has one matching PSR-4 file, grouped by role:

• Dto contains immutable data and configuration shapes.
• Service contains cohesive collector behavior such as selection, buffering, replay, timelines, deep inspection, and disk spooling.
• Contract defines the two non-blocking export seams.
• Enum, Diagnostics, and Exception contain their corresponding domain types.

Behavior-rich services remain intact rather than being divided into pass-through classes. Composer autoloading is verified without manually preloading source files.

Run its standalone verification:

composer test

The verifier checks deterministic behavior, hard bounds, signed Control API policy loading, kill-switch and local-mode behavior, and the executable p50/p99 benchmark. Checked-in compatibility and benchmark evidence is in docs/compatibility.md.

The disk spool requires a filesystem with atomic same-directory rename and PHP streams that support file and directory fsync. It fails explicitly when those guarantees are unavailable. Each PHP-FPM or worker process must use its own spool directory. A shared spool without external process coordination is unsupported.

Framework installation

Install the package and configure the local spool through environment variables:

composer require build-gaia/php-collector

CHRONOS_PHP_ENABLED=true
CHRONOS_PHP_ORGANISATION=tenant-a
CHRONOS_PHP_PROJECT=project-a
CHRONOS_PHP_APPLICATION=my-application
CHRONOS_PHP_AGENT_VERSION=dev-main
CHRONOS_PHP_SPOOL_DIRECTORY=/var/lib/chronos/php

Laravel 10–12 discovers ChronosServiceProvider from Composer metadata. The provider installs the global request middleware; no application middleware, service provider, kernel, route, or test changes are required.

Symfony applications register the bundle once in config/bundles.php:

Chronos\PhpCollector\Framework\Symfony\ChronosBundle::class => ['all' => true],

The bundle decorates http_kernel; no application event subscriber, controller, route, or test changes are required. A Symfony Flex recipe can automate the bundle registration when one is published.