Sdk Symfony Laravel Package

Product Decisions This Supports

• Feature gating and progressive rollout. The bundle autowires a single Mira\Flags\MiraFlags per process, so a PM can ship dark features, run percentage rollouts and kill-switch a surface without a redeploy — provided the team is disciplined about reading flags at the right boundary.
• Buy vs. build on flags + product analytics. This is a thin Symfony integration over mirafive/sdk-php. Adopting it means buying the flag/event plane rather than maintaining an in-house flag table, exposure logging, batching and delivery pipeline. The decision to evaluate is "vendor SDK vs. internal flag service," not "this bundle vs. writing our own bundle."
• Server-side event instrumentation without front-end tagging. Events are buffered and flushed on kernel.terminate / console.terminate, so backend-only actions (checkout, provisioning, job completion) become measurable without a JS tracker. This unlocks funnel and conversion analysis the front end cannot see.
• Instrumentation scope decisions. Because both Mira and MiraFlags are no-ops when no secret key is present or enabled: false, the PM can approve shipping instrumented code paths everywhere with a per-environment switch — a real lever for staging vs. production data hygiene and for GDPR-style "collect nothing in EU until reviewed" positions.
• Async delivery is a cost/latency trade-off the PM should own. messenger: true routes buffered batches through Symfony Messenger so requests do not pay the cost of an outbound call; send() remains synchronous for events that must not be dropped. Choosing per-event sync vs. queued is a product decision about durability vs. page latency, and it should be documented in the instrumentation standard.
• Experimentation throughput. Flags refresh on a configurable interval (flags.refresh_seconds) with optional cache. Shorter intervals mean faster experiment ramp and faster rollback; longer intervals mean less load. That is a product-visible setting, not just an ops knob.
• Roadmap sequencing. With flags and a bin/console mirafive:check smoke test, a PM can commit to "launch behind a flag, ramp over N days, remove the flag by date" as a standard lifecycle rather than a per-team negotiation.
• QA and release-confidence investment. MiraFake plus the InteractsWithMira trait means test suites can assert flag states and emitted events in CI. This lowers the cost of instrumenting aggressively, which is usually the real bottleneck on measurement quality.

When to Consider This Package

Adopt when:

• The application is Symfony (this release is a Symfony bundle using AbstractBundle; despite the framing, it is not a Laravel package — Laravel teams should evaluate the core mirafive/sdk-php or a Laravel adapter instead). Non-Symfony PHP stacks get nothing from this release.
• You already use, or are prepared to standardise on, MiraFive as the flag/event backend. This bundle is a wiring layer; it has no value without the service behind it.
• You run long-lived workers (Messenger consumers, RoadRunner/Swoole-style runtimes). The bundle explicitly flushes on kernel.reset and after each handled or failed message, and disables the core's shutdown flush. That is the correct shape for worker safety and is the strongest technical argument for using the bundle rather than hand-wiring the SDK.
• You use Twig and want the tracker tag and flag bootstrap injected without bespoke template plumbing. The Cache-Control: private, no-store on the flag bootstrap response is a meaningful default — it prevents a shared cache from serving one user's flag state to another.
• You want environment-driven configuration (MIRAFIVE_*) rather than config files holding secrets, and you want secrets to be able to arrive as empty so the SDK becomes a no-op in environments that should not report.
• Your testing culture justifies the fake. If nobody writes assertions against flags, that capability is unused weight.

Look elsewhere when:

• You are on Laravel, or any framework without Symfony's bundle/DI semantics — including plain PHP, Drupal, WordPress, Slim. The core PHP SDK is the relevant artefact there.
• You want a self-hosted or open-source flag system. This is a client for a hosted product; there is no local evaluation engine described here.
• You need flag evaluation in the browser or at the edge only. mirafive_flags() bootstraps flags server-side; client-side decisions still depend on that payload.
• You cannot accept a 1.0.0, first-release integration on a critical path. There is no track record here: no version history, no deprecation policy, no documented upgrade path. For a revenue-critical flag check, budget for a spike and an escape hatch (the underlying core SDK is the fallback).
• You need guarantees this release does not make explicit: retry/backoff on delivery failure, ordering, at-least-once semantics for Messenger batches, PII scrubbing, data residency, or a documented SLA. Those are the questions to put to the vendor before committing.
• Your scale makes flag refresh a real cost. Per-process flag caches with a refresh interval are fine for a handful of web nodes; at high fan-out with aggressive refresh, you are adding a periodic dependency to every process.
• You use Messenger but cannot tolerate silent loss — if the transport is backed up or a worker dies, buffered events are in the queue, not on disk. If the event stream is a billing input rather than an analytics input, use synchronous send() or a different transport.

Open questions to resolve before adoption: the licence terms, the behaviour when flag fetch fails (fail-open vs. fail-closed), whether test mode and production can be distinguished in reporting, and how secrets are rotated without a redeploy.

How to Pitch It (Stakeholders)

To executives — one paragraph. This is a small, standard integration that lets us turn features on and off for specific customers without shipping code, and simultaneously measure what those customers do. That combination is what makes progressive rollout and pricing/packaging experiments possible on a predictable cadence instead of a quarterly release cycle. It is a thin adapter over a vendor SDK we would otherwise wire by hand, so the build cost is near zero and the main commitment is the subscription and roughly a sprint of instrumentation work. The risk is that it is a first release from a single vendor, so I would recommend a bounded pilot on one non-critical surface with a documented fallback before we make it the default.

To engineering — the technical case. It removes bespoke wiring: autowired Mira and a single per-process MiraFlags, config bound to MIRAFIVE_*, and correct lifecycle handling that is genuinely tedious to get right — flush on kernel.terminate and console.terminate, flush on kernel.reset so worker runtimes do not bleed flags or events across requests, and flush after each handled or failed Messenger message with the core's own shutdown hook disabled to avoid double-flushing. Optional DeliverBatch delivery hands the buffered batch to the worker's own client byte for byte, so the payload does not get re-serialised and reshaped. mirafive:check gives us a deploy smoke test, and MiraFake plus InteractsWithMira gives us testable flags. Secret-less or enabled: false environments record nothing, so local and CI stay clean.

To security and compliance. Credentials come from environment variables, not committed config. The flag bootstrap response is marked private, no-store, so flag state cannot be cached and served to the wrong user. The SDK can be disabled per environment, so we can ship the code and enable collection only where it has been reviewed. What we still need from the vendor: data residency, retention, whether payloads can carry PII, and the failure mode when the flag service is unreachable.

The honest caveat to state in the room. The request frames this as a Laravel/PHP package, but v1.0.0 is a Symfony bundle. If the estate is Laravel, this release is not the artefact to adopt — the decision is about the underlying SDK, and this assessment should be re-run against the Laravel integration when there is one. Separately, a first 1.0.0 release with no version history means our recommendation should be a scoped pilot with defined success criteria (rollout lead time, event completeness, no measurable latency regression) rather than a fleet-wide default.