Php Core Laravel Package

Getting Started

What v1.0.0 actually is: the shared, framework-agnostic telemetry core, not a Laravel-specific package. Treat it as a dependency you compose into your app rather than something you artisan your way through. The 1.0.0 tag mostly buys you API stability and a wider PHP floor/ceiling (8.2–8.5).

1. Check your runtime first. php -v before anything else. If you're on 8.1 you're locked out; if you're on 8.5 you're on the newest supported version, which is exactly the kind of thing to smoke-test rather than assume — 8.5 is recent enough that transitive dependencies may lag even though the core claims support.
2. Install. composer require <vendor>/apirelio-telemetry-core:^1.0. Pin with ^1.0 now that it's stable; during 0.x you'd have wanted ~0.x.y.
3. Read composer.json before the README. Look for two things: a laravel key under extra (auto-discovery of a service provider = zero-config) and whether a psr/* or framework adapter is a require or a suggest. A "core" that suggests an adapter is telling you the wiring is your job.
4. Find the seams. Skim src/ for the public entrypoints — typically a tracer/meter factory, an exporter interface, a context/scope object, and a sampler. Those four are the whole surface area you'll actually touch.
5. First use case: instrument one endpoint and one queued job end-to-end, export to your backend, and confirm a single correlated trace appears. Do this before writing any abstraction — you want to see the raw output once so you know what "working" looks like.

If a Laravel adapter package exists alongside the core, install it and read its service provider instead — that's where config keys and container bindings will be documented.

Implementation Patterns

Hide the core behind one small internal service. You will not want Apirelio\...\Tracer::startSpan() calls scattered through controllers. Wrap it:

final class Telemetry
{
    public function __construct(private readonly TracerInterface $tracer) {}

    public function span(string $name, array $attrs = [], Closure $fn): mixed
    {
        $span = $this->tracer->startSpan($name, $attrs);
        try { return $fn($span); }
        finally { $span->end(); }
    }
}

Bind the core's concrete tracer to this in a provider. When the core's API shifts in 1.1, you edit one file.

Propagate context at the framework boundaries, nowhere else. Three places matter in a Laravel app:

• HTTP in: middleware that extracts incoming traceparent-style headers into the core's scope and starts a root span.
• Queue jobs: job middleware (or a JobProcessing listener) that serialises the current context into the payload on dispatch and restores it on handle(). Without this every queued job starts a fresh orphan trace — the single most common integration failure.
• Scheduled commands / Artisan: a console hook so schedule:run children aren't invisible.

Sampling belongs in config, and it belongs to be environment-aware. 100% in local, parentbased_traceidratio in production. Read the ratio from config() at boot, not per-request — you want it fixed per worker.

Make tests quiet by default. Bind a no-op exporter in phpunit.xml's env block so the suite doesn't emit network calls, then write a handful of tests against an in-memory exporter that assert span names and attributes. Assert on names and counts, not on timings.

Octane and long-running workers: confirm the core resets its active scope between requests. If there's no documented reset hook, add terminating middleware that clears the scope explicitly. Leaked spans across requests produce absurd parent-child graphs and are miserable to diagnose.

Gotchas and Tips

• "Core" means no auto-discovery, probably. If extra.laravel is absent, nothing happens until you write a provider. Don't file a bug — read the install docs for the adapter.
• Fresh 1.0.0 = thin real-world mileage. The API is stable by promise, but expect the first patch release within weeks. Run it in staging against your actual backend before trusting it in prod, and keep the version pinned in composer.lock so a 1.0.1 doesn't land on a Friday.
• PHP 8.5 support is a claim, not a guarantee. It says supported; it doesn't say "battle-tested." If you're on 8.5 you are the test suite.
• Tag cardinality will bite you. Anything you stuff into span attributes gets indexed downstream. user_id, order_id, request IDs → fine. Full URLs, query strings, exception messages with interpolated values → your telemetry bill and your query performance. Sanitise at the wrapper layer, not at each call site.
• Attribute naming is a schema, not a comment. Pick a convention (app.user.id, http.route) on day one. Renaming later invalidates every dashboard you built.
• Record exceptions, don't swallow them. The try/finally above ends the span; it does not mark it errored. Call the core's recordException() in a catch and rethrow. Silent error spans are worse than no spans.
• Debugging with no collector: most cores ship a console/log exporter or a no-op. Find it, bind it locally, and assert spans in a test — far faster than tailing a collector.
• Don't put the core in hot loops. Per-row instrumentation in a 10k-iteration job is a real latency tax. Instrument the job, plus coarse phases within it.
• Extension points to note for later: custom exporter (for a backend the core doesn't ship), span processor (to enrich attributes globally — e.g. tenant ID), and sampler (per-route overrides). These are the three places to hook rather than fork.
• Watch the changelog for the 0.x → 1.0 delta if you ever ran a pre-release. Stable 1.x is the point at which the maintainers stopped making breaking changes, which means anything you wrote against 0.x is now your migration problem, not theirs.