Sdk Php Laravel Package

Product Decisions This Supports

• Build vs. buy for the instrumentation layer. A single composer require mirafive/sdk-php delivers buffered event ingest and server-side flag evaluation. That moves roadmap capacity from plumbing (batching, retries, idempotency, cache invalidation) to product surfaces — a decision worth quantifying against an estimated build effort of several engineer-weeks plus permanent maintenance.
• Gating and progressive rollout. MiraFlags with ETag revalidation and an optional PSR-16 cache means a PM can ship a feature dark, then ramp by segment without a deploy and without a network call on the hot path.
• Consent and privacy posture as a product decision, not a code branch. Consentless vs. full collection modes are first-class, and identifiers are refused in consentless mode. That lets you commit to a defensible per-market position once and encode it, instead of auditing ad-hoc if ($region) checks.
• Trust in experiment readouts. Server-counted exposures record the exposure where the decision is actually made, immune to ad blockers, client clock skew and late JS. That directly improves confidence in A/B results and reduces "the numbers look wrong" cycles.
• Degradation policy for third-party dependencies. flushDeadlineMs (3 s), connectTimeoutMs (1 s) and a 30 s circuit breaker after a failed flush or segment lookup give an explicit answer to "what happens to the user experience when the vendor is down?" — supporting a standing decision that analytics and flags are non-blocking, best-effort dependencies.
• Cost and volume control. Batches capped at 1000 events / 1 MiB plus per-batch idempotency keys bound ingest spend and eliminate duplicate-count disputes; rejected validation_failed events are dropped and reported rather than retried forever.
• Keeping telemetry off the request path. handOff / deliverPrepared() for queued delivery, flushOnShutdown, and enabled: false for local and test environments support the decision to treat collection as asynchronous infrastructure rather than inline work.
• Vendor portability. PSR-18 transports and PSR-16 caches, plus document: accepting a MiraFlags::snapshot() JSON, mean the exit cost is configuration, not a rewrite.

When to Consider This Package

Adopt when:

• The stack is Laravel/PHP and you are buying rather than building analytics ingest and feature flags.
• You need server-side flag evaluation with local caching — low-latency, no per-request network round trip, and deterministic behavior during a vendor outage.
• Consent requirements vary by market and you need a supported mode switch rather than custom branching.
• You want standards-based interop, not lock-in: bring your own PSR-18 client and PSR-16 cache; feed document: from your own config, CI artifact, or snapshot().
• You need queue-friendly delivery and clean local/test seams before you will let a third-party SDK into the request path.

Look elsewhere or wait when:

• You need an experimentation statistics engine (sequential testing, CUPED, Bayesian analysis). This package is transport plus evaluation, not analysis.
• Push/streaming flag updates or sub-second multi-region propagation are hard requirements; this is ETag revalidation plus flagsRefreshSeconds polling.
• You require warehouse-native or fully self-hosted analytics with no third-party endpoint.
• Non-PHP services dominate the estate — flags then need a parallel SDK per language; confirm the other SDKs share the same protocol and MIRA FIVE fixtures.
• You need a vendor SLA and an operating track record. v1.0.0 is the first release on the v1 protocol; treat it as a low-maturity dependency and stage adoption accordingly.

How to Pitch It (Stakeholders)

For executives. One integration replaces weeks of internal plumbing for analytics and feature flags — the part we would otherwise build once and maintain forever. It ships with the guarantees teams usually discover they need after an incident: batching, deduplication, retries with jittered backoff, explicit timeouts and a circuit breaker so a vendor outage degrades gracefully instead of taking the product down. Consent modes let us answer privacy requirements per market without a rewrite, and the PSR standards mean we can swap HTTP clients and caches rather than marry the vendor. The honest risk: this is a first public release — so we adopt behind an enabled switch, with a staged rollout and a documented fallback.

For engineering. A small, standards-based client. Buffered track() / identify() with an explicit send() and flush(); batches capped at 1000 events and 1 MiB; idempotency keys per batch so retries resend a byte-identical body and never double-count. Retries cover 408, 429, 5xx, timeouts and network errors with full-jitter backoff and a bounded Retry-After; a collector-rejected event (validation_failed) is dropped and reported while the rest of the batch is resent under a derived batch id. Transports are cURL, PHP streams, or any PSR-18 client; cache is any PSR-16 store, which is also where exposure marks, segment memberships, lookup back-off and the circuit-breaker state live. The flag document is ETag-revalidated with segment lookups and server-counted exposures, and the evaluator passes the shared MIRA FIVE fixtures. handOff / deliverPrepared() push delivery onto the queue, flushOnShutdown covers PHP-FPM, enabled: false keeps local and CI clean, Mira::DEFAULT_HOST makes the endpoint overridable, and the bootstrap block for the browser SDK is escaped by default so we don't ship an XSS hole alongside our feature flags.