seamward/php-collector

Framework-neutral PHP collector for Seamward integration evidence.

v0.1.0-alpha.1 2026-08-31 20:53 UTC

Requires

• php: ^8.3
• ext-mbstring: *

Requires (Dev)

• laravel/pint: ^1.0
• pestphp/pest: ^4.0 || ^5.0
• phpstan/phpstan: ^2.0

MIT

• Seamward contributors

• api
• collector
• integration
• webhook
• observability

Published on Packagist.org on 2026-08-31 21:02 UTC

README

Framework-neutral PHP 8.3+ collector core for building strictly validated, redaction-safe Seamward observation envelopes, observing HTTP, webhook, queue, and scheduled-feed boundaries, buffering evidence in bounded memory, and delivering signed batches through an injected transport.

Status: alpha. This package is available under the MIT license.

Install

composer require seamward/php-collector:^0.1@alpha

Use

use Seamward\Collector\Collector;
use Seamward\Collector\Configuration\Connection;
use Seamward\Collector\Observation\Observation;
use Seamward\Collector\Observation\Operation;

$collector = Collector::connect(
    connection: Connection::fromCredentials($connectionKey, $ingestToken),
    transport: $transport,
);

$collector->record(new Observation(
    operation: Operation::outboundHttp('POST', '/v1/candidates'),
    statusCode: 201,
    durationMs: 48,
    payload: (object) ['id' => 'local-value'],
));

$collector->flush();

Queue publishes, queue consumers, and scheduled imports or exports have first-class wrappers. They preserve the callback return value and rethrow the callback's original exception:

$result = $collector->observeQueuePublish(
    queueName: 'candidate-events',
    message: $message,
    publisher: fn ($message) => $queue->publish('candidate-events', $message),
);

$rows = $collector->observeScheduledFeed(
    feedName: 'nightly-candidate-import',
    direction: 'inbound',
    payload: $rows,
    handler: fn ($rows) => $importer->import($rows),
);

Pass deployment: ['service' => 'candidate-api'] to Collector::connect() to override release context. Otherwise, the core recognizes the same bounded Seamward and deployment-platform variables as the Node.js collector. A valid per-observation deployment takes precedence over the collector default.

Implement Seamward\Collector\Transport\Transport with the HTTP client already used by the host application. The request passed to the transport contains the signed JSON body and delivery headers.

The collector sends structural shapes, fingerprints, operation metadata, and keyed hashes. Raw payload values, headers, ingest tokens, and unhashed correlation identifiers are never placed in an envelope.

Redactor::payload() and Redactor::headers() provide Node-compatible helpers for separate local logging or storage pipelines. They are not needed to keep values out of Seamward envelopes because the envelope has no body or header field.

Development

composer install
composer test
composer analyse
composer format -- --test

The package-local fixture at tests/fixtures/collector-conformance-v0.2.json is checked against the shared Seamward contract before every release. It verifies that PHP and Node produce the same shapes, fingerprints, keyed hashes, signatures, and full envelope.