Feature Flag Bundle Laravel Package

Product Decisions This Supports

• Roadmap sequencing on a legacy stack. If the product still ships from a Symfony 4.4 / PHP 7.4 application, this bundle is the cheapest way to decouple "deploy" from "release." That directly enables dark launches, canary-by-cohort releases, and pre-built-but-hidden features without waiting for a platform upgrade.
• Build vs. buy (vs. adopt). The realistic alternative for a legacy Symfony app is either an in-house if ($config->get('feature_x')) service or a commercial flag platform. This package sits in between: MIT licensed, no runtime dependency beyond the framework, and it provides the service wiring, Twig helpers, and a profiler panel that an in-house implementation would take a sprint or two to reach parity on.
• Migration strategy as a first-class deliverable. The package deliberately keeps the upstream Ajgarlag\FeatureFlagBundle\ namespace. That makes the eventual Symfony 6+/PHP 8 upgrade a Composer constraint change rather than a code rewrite. A PM can treat this as a bridge dependency with a known, near-zero-cost exit — which is a much easier thing to get approved than a custom abstraction.
• Vendor-risk and architecture decisions on toggles. Because flags are resolved through ProviderInterface rather than hard-coded booleans, the choice of where flag state lives (config, Doctrine, Unleash/GitLab, LaunchDarkly) stays reversible. This lets a PM defer the "which flag platform do we standardise on" decision without blocking feature delivery.
• Use cases it realistically supports: kill switches for risky integrations, per-environment behaviour toggles, hiding half-finished UI from customers, cohort gating for pilots, and context-aware branching (user, IP, hostname, date) — the @AsFeature("xmas") example is a genuine, if small, product use case.
• Not supported, and should not be promised to stakeholders: percentage rollouts, targeting rule builders, experimentation/statistics, flag expiry policy, audit trails, or an admin UI. Each of those is either a provider you write yourself or a different product entirely.

When to Consider This Package

Adopt it when all of the following are true:

• The application is pinned to Symfony 4.4 and PHP 7.4/8.0 — this fork exists specifically for that combination and is the only reason to prefer it over upstream.
• You need code-level toggles, not a feature-management platform. The mental model is "a callable returns a value, compare it to an expected value."
• You are comfortable writing your own provider if flags must be database-driven or remotely managed. The bundled ServiceProvider/ChainProvider handle the in-process cases; anything stateful is your code.
• The team accepts the EOL security posture of Symfony 4.4. The maintainer explicitly disabled Composer's audit.block-insecure in CI, and flags this trade-off in the changelog. That is honest, but it is a decision someone owns.
• You have a named owner for the exit plan. The package is a bridge with a one-maintainer bus factor and zero dependents; treat it as scaffolding, not foundation.
• Route-level gating is acceptable at the controller or kernel.controller listener level. Symfony 4.4 cannot evaluate services in route condition expressions, so there is no declarative route gating here.

Look elsewhere when:

• The stack is Laravel, not Symfony. Despite being a PHP package, this is a Symfony bundle — bundle registration, service tags, Doctrine annotations, and Twig extensions. Laravel teams should use Laravel Pennant, or a vendor SDK (LaunchDarkly, Unleash, Flagsmith, GrowthBook).
• You are on Symfony 5.4+ / PHP 8.1+. Use the upstream ajgarlag/feature-flag-bundle directly; it uses native PHP 8 attributes and is actively targeted at modern Symfony. This fork is strictly the legacy path.
• You need native PHP 8 attributes. PHP 7.4 has no attributes, so features are declared with the @AsFeature Doctrine annotation, which cannot be repeated on the same class or method. Multiple flags on one class require falling back to the ajgarlag.feature_flag.feature service tag — a papercut that will annoy teams with flag-heavy services.
• You need targeting rules, experimentation, or an admin console. Those are platform features, not bundle features. Writing them on top of ProviderInterface is possible but is a product in itself.
• Procurement requires a supported dependency. Zero stars, zero dependents, and a maintainer whose releases are CI maintenance only is a signal about support depth, not code quality. If your risk register treats unsupported dependencies as blockers, this fails that test regardless of merit.

How to Pitch It (Stakeholders)

One line: a small, MIT-licensed Symfony bundle that lets a legacy Symfony 4.4 application ship features behind toggles — cheap to adopt, cheap to leave.

For executives: this is not a platform investment. It is a tactical enabler that costs roughly a Composer line and a config entry, and it buys the organisation the ability to release code without immediately exposing it to customers — the minimum prerequisite for canary releases and kill switches. There is no licence fee, no data leaving our infrastructure, and no lock-in: the API is intentionally identical to a maintained upstream package, so when we upgrade off Symfony 4.4 the migration is a version constraint, not a rewrite. The risks are equally small and equally clear: a single maintainer, essentially zero community, and a stack that is already end-of-life. We should adopt it as scaffolding with a documented exit, and we should not build product commitments that assume flag-management features (targeting rules, experiments, admin UI) it does not have.

For engineering: FeatureCheckerInterface is the seam — inject it, and wrap it in an application-level interface so swapping to upstream or a vendor SDK later is a single adapter class. Prefer providers over hard-coded callables so flag state stays external to the binary. The Twig helpers (feature_is_enabled, feature_get_value) keep conditional UI out of controllers, and the web profiler collector gives per-request visibility into resolved values, which is the difference between a debuggable rollout and a guessing game. Budget the papercuts: annotation-only declarations, no repeatable annotations, and controller-level rather than route-level gating.

Decision requested: approve as a time-boxed bridge dependency tied to the Symfony 4.4 → modern-stack upgrade, with an owner, an exit criterion, and an explicit instruction to route all flag access through one application-level interface.