Sdk Php Laravel Package

Technical Evaluation

The v1.0.0 release is a framework-agnostic PHP analytics and feature-flag SDK, not an explicitly Laravel-packaged integration. The public surface is MiraFive\Mira for event ingestion and MiraFive\Flags\MiraFlags for flag evaluation. Architecture fit is therefore moderate: the SDK is Composer-installable and standards-oriented, but Laravel adoption depends on writing or validating a thin adapter for container bindings, configuration, consent resolution, cache wiring, HTTP client selection, and lifecycle flushing.

Key architecture considerations:

• Event ingestion uses buffered track() and identify(), immediate send(), and lifecycle flush(). This fits request/response Laravel apps if flush is wired into termination or a queued delivery path; it is riskier in queue workers, Octane, and other long-running processes unless flush points are explicit.
• Batching is bounded at 1,000 events and 1 MiB, with idempotency keys and byte-identical retries. This is a sensible delivery model but requires the TPM to validate throughput assumptions, payload sizing, and duplicate suppression with the collector.
• Transport flexibility is good: cURL, PHP streams, or any PSR-18 client. PSR-16 caching is optional but central to flags, exposure marks, segment memberships, lookup back-off, and the shared circuit breaker. This aligns with Laravel’s ecosystem but needs adapter validation rather than assuming drop-in compatibility.
• Consentless and full collection modes are a major product/compliance decision. In consentless mode, identifiers are refused. That is the right safety posture, but it can break event shapes or product expectations if the application still expects identified users. Consent-state mapping must be designed, not inferred.
• The flag evaluator passes shared MIRA FIVE fixtures, supports ETag revalidation, segment lookups, server-counted exposures, and an escaped bootstrap block. That is a credible server-side flag offering, but the TPM should treat “passes fixtures” as necessary, not sufficient; production validation needs real flag documents, stale-cache behavior, and browser bootstrap security checks.
• Outage protection is present: 3 s per-flush deadline, 1 s connect timeout, and a 30 s circuit breaker after failed flush or segment lookup, shared through PSR-16. This is operationally thoughtful, but the shared breaker can suppress traffic across processes and must be observable. A 30 s breaker may be acceptable for analytics but should be reviewed for flag-dependent critical paths.
• v1.0.0 is a first release. The API may be stable by declaration, but there is no migration history, no prior assessment, and no evidence of Laravel-specific support in the release notes. Treat initial adoption as a controlled pilot, not an assumed enterprise-standard integration.

Key questions for the vendor or integration owner:

• Is there a Laravel service provider, facade, publishable config, and auto-discovery support, or must the application provide all wiring?
• Which PHP and Laravel versions are supported, and which PSR-18/PSR-16 implementations are tested?
• How should handOff and deliverPrepared() be used with Laravel queues, and what are the retry/idempotency expectations from the queue worker?
• What is the exact behavior when an identifier is refused in consentless mode: exception, dropped event, or reported result?
• How are validation_failed drops, circuit-breaker opens, refused identifiers, and unreadable flag documents exposed for observability?
• What are the bounds on Retry-After, and how is full-jitter backoff configured?
• How are API keys, host configuration, and Mira::DEFAULT_HOST overrides managed across environments?
• Is flush() on shutdown reliable under PHP-FPM, Laravel Octane, queue workers, and destructors, or should production rely only on explicit termination hooks?
• What is the PSR-16 cache-key strategy and TTL for flags, exposures, segment membership, and circuit-breaker state?
• Are there documented limits, rate limits, data residency constraints, and browser bootstrap CSP requirements?

Integration Approach

Stack fit is best described as “Laravel-compatible with adapter work.” The SDK’s use of PSR-18 and PSR-16 is the right foundation, and enabled: false supports local/test environments cleanly. However, the release notes do not show a Laravel package, service provider, config file, or queue integration. A TPM should plan a small integration layer rather than expecting a native Laravel package.

Recommended integration approach:

1. Dependency and configuration spike: Add mirafive/sdk-php behind a feature branch, confirm PHP/Laravel compatibility, and bind MiraFive\Mira and MiraFive\Flags\MiraFlags as container singletons or scoped services. Centralize host, mode, cache store, HTTP client, flushOnShutdown, flagsRefreshSeconds, and enabled configuration in Laravel config and environment variables.
2. Adapter boundary: Wrap the SDK behind an application-owned interface for event tracking and flag evaluation. This isolates the app from SDK API changes, makes consent handling explicit, and avoids scattering MiraFive calls across controllers, jobs, and models.
3. Consent and identity mapping: Decide whether production uses full or consentless mode. Map the application’s consent source to SDK configuration and test identifier refusal behavior. Do not allow analytics calls to bypass consent logic.
4. Delivery path: Start with synchronous buffered tracking plus explicit flush in a termination hook or middleware. Evaluate handOff / deliverPrepared() for queued delivery before high-volume rollout. For queue workers and Octane, define explicit flush points; do not rely solely on shutdown or destruction.
5. Caching and HTTP client: Select a PSR-18 client already used by the application where possible. Validate the Laravel cache store as a PSR-16 cache for flags, exposures, segment membership, and circuit-breaker state. Confirm key isolation and TTLs in staging.
6. Flags pilot: Use MiraFlags::snapshot() and document: for local and staging evaluation. Test ETag revalidation, stale-cache behavior, consent/opt-out behavior per FLAGS.md §5.1, segment lookup, exposure marking, and escaped browser bootstrap output. Validate against the shared MIRA FIVE fixtures and at least one representative production flag document.
7. Observability before broad release: Add logs and metrics for flush failures, retry attempts, circuit-breaker state, validation_failed events, refused identifiers, unreadable documents, and dropped batches. The SDK reports some of these, but the application must route them into its monitoring stack.
8. Progressive rollout: Use enabled: false in local/test, enable in staging with a non-production project or host, then canary a small production surface. Roll back by disabling the SDK, removing flush hooks, and retaining the adapter boundary. If replacing an existing analytics or flag provider, dual-write during the pilot and compare delivery and flag-evaluation parity.

Compatibility risks to resolve early: long-running process lifecycle, queue-worker flushing, PSR-16 cache semantics, PSR-18 client discovery, consent storage, and whether the SDK’s shutdown flush can block request termination within the 3 s deadline. The migration path is greenfield rather than a breaking upgrade, but initial adoption should still be sequenced as an integration spike, staging validation, canary, and then production rollout.

Operational Impact

Maintenance burden is moderate and front-loaded. The package is new at v1.0.0, so the team should pin a major version, monitor releases, and keep the adapter layer thin enough to absorb SDK changes. The PSR abstractions reduce lock-in, but they also mean the application owns more integration code than a native Laravel package would require. A runbook should cover configuration, consent mode, cache selection, flush points, and rollback via enabled: false.

Support and observability need deliberate ownership. The SDK provides useful seams, but production support requires alerts on flush failures, circuit-breaker opens, retry storms, dropped validation_failed events, refused identifiers, and unreadable flag documents. Vendor documentation for PROTOCOL and FLAGS should be available to on-call staff, not just to the implementing engineer.

Scaling characteristics are reasonable for an SDK of this type: batches cap at 1,000 events and 1 MiB, flags evaluate locally after retrieval, and ETag revalidation reduces document transfer. The main scaling risk is not the batch size but delivery coupling. A synchronous flush with a 3 s deadline and 1 s connect timeout can still add latency if placed poorly. High-volume applications should use queued delivery or a background flush strategy. The shared PSR-16 circuit breaker is operationally efficient but can create correlated suppression across all processes; that must be visible in dashboards and reviewed against flag-critical use cases.

Primary failure modes:

• Collector outage or latency opens the circuit breaker and can drop or delay analytics and flag refreshes.
• validation_failed events are dropped and partially resent under a derived batch id, so downstream counts may differ from application-side counts.
• Identifiers in consentless mode are refused, which may produce expected but surprising data gaps.
• An unreadable flag document is reported, but the application must decide whether to fail closed, use stale cache, or fall back.
• Shutdown or destruction flush may not run reliably in Octane, queue workers, or abnormal terminations; explicit flush points are required.
• Cache unavailability can affect flag freshness, exposure deduplication, segment membership, and breaker state.
• Browser bootstrap output must remain correctly escaped; this is a security-sensitive integration point.
• Empty idempotency keys are refused, so key generation must be guaranteed by the integration.

Ramp-up should be small and time-boxed: one backend engineer for the SDK/Laravel adapter, one product or analytics owner for event schema and consent behavior, and one platform/on-call representative for observability and rollout. A basic integration spike is likely 1–2 engineering days; a production-grade Laravel integration with consent mapping, queue delivery, caching, observability, and flag pilot is more realistically 3–5 engineering days plus staging validation. Success criteria should include no material request-latency regression, verified event delivery and idempotency behavior, correct consent-mode enforcement, flag-evaluation parity against fixtures and a real document, and an exercised rollback path.