Laravel collector API

seamward/laravel-collector adapts the framework-neutral PHP collector to Laravel 12 and 13. It requires PHP 8.3 or later and is available from Packagist as an alpha package.

Service provider

Laravel package discovery loads SeamwardServiceProvider. The provider:

merges and publishes config/seamward.php;
binds SeamwardManager with request or job scope;
registers the seamward.webhook middleware alias;
registers seamward:doctor;
flushes resolved collectors after console commands, queue jobs, and application termination.

Named connections

seamward.default selects the default connection. Each entry under seamward.connections accepts:

Key	Default	Purpose
`connection_key`	required	Public Connection key for one Integration
`ingest_token`	required	Secret, collector credential
`endpoint`	Seamward ingest API	HTTPS delivery endpoint
`redaction_policy_version`	`shape-only-v1`	Audit label for local shape extraction
`hash_key`	locally derived	Optional explicit keyed-hash material
`hash_namespace`	locally derived	Optional hash generation label
`deployment`	config environment	`service`, `release`, and `commitSha`
`max_queue_size`	`1000`	Bounded process-local queue
`max_batch_size`	`50`	Envelopes per request
`timeout_seconds`	`2`	Connect and request timeout

Use a separate named connection for every Integration direction and protocol boundary.

SeamwardManager

connection(?string $name = null): Collector returns and reuses the named core collector.
observeHttp(string $connection, string $method, string $routeTemplate, callable $callback, string $payloadLocation = 'response', mixed $requestPayload = null): mixed records request-side or response-side structure while preserving the response or exception. The optional parameters are appended for compatibility.
observeQueuePublish(...) and observeQueueConsumer(...) delegate explicit broker callbacks to the named core collector.
observeScheduledFeed(...) observes one explicit scheduled import or export callback.
record(Observation $observation, ?string $connection = null): void records custom core observations.
flush(?string $connection = null): void flushes one named connection or all resolved collectors.
stats(string $connection): array returns delivery and build counters for one named connection.

All collector build and delivery failures are suppressed. The callback's own exception is recorded and rethrown unchanged.

The queue and feed methods preserve callback results and exact host exceptions. They never acknowledge a message, apply a retry, control a dead-letter queue, or schedule a job. Laravel job events only trigger flushing.

ObserveWebhook middleware

ObserveWebhook accepts the connection name and stable route template as middleware parameters. The template is required for observation. If it is omitted, the middleware records nothing instead of deriving an identity from a concrete request path that might contain customer identifiers. It records the request's JSON structure after the handler, keeps the handler response authoritative, and flushes during terminate().

Code example

Route::post('/webhooks/candidates', CandidateWebhookController::class)    ->middleware('seamward.webhook:candidate_webhook,/webhooks/candidates');

Non-JSON bodies produce a null payload shape. Headers and raw body values are never serialized into the envelope.

Diagnostics