Php Sdk Laravel Package

Getting Started

This is a v0.1.0 release of an attribution-tracking package. It ships three distinct concerns: a deterministic attribution resolver, a consent gate, and a batch transport layer. Start by confirming the actual package name and namespace from the release tag, then:

1. composer require <vendor>/<package>:^0.1
2. Publish configuration and any migrations the package provides (vendor:publish --provider=...).
3. Set the transport endpoint, API key, and environment in .env.
4. Register the service provider if it isn't auto-discovered.

Where to look first: the published config file. It controls the transport, batching thresholds, and consent behaviour — the three pillars of this release. Then read the BatchClient signature and the consent model interface, because everything you build will route through them.

First use case: attribute a registration to an originating campaign. Capture the UTM/click parameters on the landing page, persist the raw identifiers, and resolve attribution deterministically at registration time. The release notes cite "12/12 golden fixtures, 57/57 fields parity" — those fixtures are your contract. Read them before writing code; they define the exact field shape you must emit, including the consent payload and the transport envelope.

Implementation Patterns

Consent-first middleware. The consent model is a first-class component, not a helper. Gate every capture point behind an explicit consent check, ideally as middleware or a form request rule, rather than checking consent inside the controller. This keeps unconsented data from ever being persisted, which is safer than filtering at dispatch time.

Capture, then resolve — never infer. "Deterministic attribution" means the resolution follows fixed rules from recorded inputs, not heuristics. Persist the original touch parameters verbatim (params, timestamp, source) and let the package resolve. Do not normalise, lowercase, or rewrite values before they reach the resolver — you will drift from the golden fixtures.

Batch outbound events; don't send inline. The BatchClient transport is built for batched dispatch. The pattern is: accumulate attribution events during the request cycle, then flush via a queued job or terminating() callback. Flushing inline in a controller ties your response time to the transport's latency and fails silently if the batch is partial.

// Illustrative shape — confirm against the package's real API
Event::listen(RegistrationCompleted::class, function ($event) {
    if (! $this->consent->hasScope('analytics')) {
        return;
    }
    $this->attributor->record($event->user, $event->attributionContext);
    $this->batchClient->push($event->user->attributionId());
});

Dispatch the actual flush as a queued job so a slow or unavailable endpoint can't block user-facing flows. Retry the flush; the batch envelope should be safely retryable if the package is idempotent — verify this before relying on it.

Treat the golden fixtures as your integration tests. With only 11 tests in the package, you want your own suite pinning the same 57 fields. Load the fixtures, feed them through your capture → resolve path, and assert byte-for-byte parity on the emitted payload. That is the cheapest way to detect a breaking change in a 0.x release.

Wire up a lifecycle hook for flush-on-terminate. Laravel's app()->terminating() or a queue finally block is the natural place to drain the batch. Without it, small applications will accumulate events that never leave the buffer.

Gotchas and Tips

0.x means the API can move under you. Pin to 0.1.* and read the changelog before every minor bump. The 57-field parity commitment is a strong signal that the payload schema is treated as a contract — but the PHP-facing API is not yet guaranteed.

Deterministic attribution depends on stable identifiers. If your attribution key is derived from session IDs, request-cached values, or timestamps rounded to the second, the same user will resolve differently across requests. Use a persisted UUID on the user or a first-party cookie written once at capture time. Regenerating identifiers is the single most common way this class of package produces impossible debug sessions.

Consent must be checked at capture and at dispatch. Checking only at capture leaks unconsented PII into your batch buffer, where it may still hit the transport. Checking only at dispatch means you stored unconsented data. Do both; the second check is cheap.

Batch flushing is the failure surface. Three things go wrong: batches flushed before the response is sent (latency), batches never flushed (silent data loss on worker shutdown), and duplicate flushes from retry logic (double-counted attribution). Monitor flush failures explicitly — the transport is unlikely to surface these through your normal error handling. Log batch size and flush outcomes.

Field parity is not behavioural parity. 57/57 fields means the payload shape matches the reference. It does not mean your Laravel middleware stack produces the same inputs. Test with your real request lifecycle — subdomain, proxy headers, and cookie domain scope will change what gets captured.

Test coverage is thin. 11 tests across three subsystems (resolver, consent, transport) means the edge cases are on you. Priorities: consent revocation mid-session, transport endpoint returning 4xx vs 5xx, and empty/partial batch handling. The 4xx case is the dangerous one — a malformed batch may be retried until it poisons the queue.

Extension points to check early. Whether the consent model is an interface you can implement (likely, given it's called a "model" rather than a "provider") and whether the transport is swappable. If both are interposable, you can substitute a local driver in tests and a logging driver in staging without touching the resolver — that's the difference between an afternoon of integration and a week of it.