Feature Flags Laravel Package

Product Decisions This Supports

• Decouple deploy from release. Ship code dark, then ramp exposure without a redeploy. This directly shortens the time between "merged" and "in production" and removes the release-train bottleneck from the roadmap.
• Rollout strategy as a product decision, not an engineering afterthought. Environment/tenant/actor targeting lets you define cohorts in product terms — design partners, a single pilot tenant, EU region, free tier — and stage a launch through them. Useful for beta programs, regional GA, and B2B tier gating.
• Build vs. buy for the flag capability itself. This is an in-process Laravel package rather than a SaaS control plane. That changes the calculus: no per-MAU/per-seat flag pricing, no network hop on the evaluation path, no user identifiers leaving your infrastructure. Worth pricing explicitly against LaunchDarkly/Flagsmith/Unleash/GrowthBook before defaulting to a vendor.
• Flag debt becomes a tracked liability instead of an ambient one. Ownership plus expiry is the most PM-relevant feature here. It forces a named owner and a retirement date onto every flag, which turns "we have 400 flags and no idea which are live" into a reportable inventory metric. If stale flags have ever caused an incident or a slow cleanup quarter, this is the argument.
• Typed flags reduce a specific incident class. Stringly-typed flags that return "false" (truthy) are a recurring self-inflicted outage. Typed definitions with structured payloads also let a flag carry a config variant, which can absorb some "we need a config service" requests.
• Stable rollout protects experiment and UX validity. Consistent bucketing means a given actor doesn't flip between variants across requests. Without it, user-visible toggling generates support tickets and quietly corrupts any A/B readout you layer on top.
• Telemetry boundaries let you decide where exposure data lives. If the analytics contract says experiment exposure events go to your warehouse, not a vendor, this is a design decision you can actually enforce rather than a policy you hope holds.
• Kill switches for expensive or fragile dependencies. A PM-owned lever to disable a flaky integration, a costly AI call, or a new checkout path without an emergency deploy — worth scoping as a resilience/reliability line item, not just a growth tool.

When to Consider This Package

Adopt when most of these are true:

• The stack is Laravel-first and flags are evaluated server-side in the PHP request path (not in a JS client).
• You genuinely need tenant + actor + environment targeting natively — multi-tenant B2B is the sweet spot here.
• You have a data-handling constraint (PII, DPA review, data residency) that makes shipping user identifiers to a third-party flag SaaS expensive or blocked.
• You want flag lifecycle governance — owner, expiry — more than you want a toggle UI.
• A platform engineer can own the dependency: pin the version, fork or vendor it if needed, and wrap it behind an internal interface.
• Flag volume or MAU makes per-seat SaaS pricing a real line item.

Look elsewhere when:

• Non-engineers must operate flags. PMs, marketing, or support flipping toggles requires a hosted UI, RBAC, and an audit log. This package is a library, not a control plane.
• The estate is polyglot. Flags need to evaluate consistently in Node, Go, or Python services; you need multi-language SDKs.
• You need experiment analysis. This gates exposure; it does not do significance testing, sequential tests, or variance reduction. Pair it with an analysis layer or buy a platform.
• You need compliance artifacts — SOC 2, SSO/SCIM, change approval workflows, vendor SLA. Zero stars and zero dependents means no support contract and a real bus-factor risk.
• A flag sits on a revenue-critical kill switch today. Maturity doesn't yet justify putting the emergency brake on an unproven single-maintainer dependency.
• Extreme hot-path throughput, where you should first measure the config/cache lookup cost per request.

Practical adoption path: pilot on internal or non-critical flags, keep all call sites behind your own Flags interface so the vendor is swappable, and treat the upstream repo as a fork candidate from day one. Note that the release metadata warrants a sanity check before you rely on a cadence — the signals here are thin enough that "verify, don't assume" is the right posture.

How to Pitch It (Stakeholders)

To executives (one paragraph): We need a way to release features gradually and turn them off instantly without redeploying. The default answer is a flag SaaS, which charges per user and puts a third party in our request path. This is a Laravel-native alternative that removes that recurring cost and keeps user data inside our infrastructure. Its differentiator is governance: every flag carries an owner and an expiry date, which directly attacks the stale-flag problem that has cost us cleanup time and at least one incident. The risk is maturity — it's early-stage open source with no dependents — so we'd adopt it behind an internal abstraction, pilot it on non-critical flags, and retain the ability to swap vendors without touching product code.

To engineering: Low integration cost — it's a Laravel package, flags are typed, targeting is declarative, and telemetry is a boundary you plug into rather than a vendor you're bound to. Consistent bucketing is handled. The ask is that we wrap it in our own flag interface and pin the version so upstream immaturity is contained.

To product and analytics: We get environment/tenant/actor targeting and stable bucketing for free, and exposure events can land in our own warehouse instead of a vendor's — which keeps experiment data ours and simplifies privacy review. It does not replace the analysis layer; plan for that separately.

Metrics to instrument from day one: flag count by owner and days-to-expiry, percentage of flags past expiry, rollout ramp time (merge → 100%), and kill-switch activations per quarter. Those four numbers are the business case in retrospect.