Toggle Bundle Laravel Package

Technical Evaluation

Bottom line: this is a Symfony bundle, not a Laravel package. It cannot be installed into a Laravel application as-is, and its ecosystem signals (89 stars, 0 dependents, dormant upstream) mean we would be adopting a small abandoned codebase rather than a maintained dependency. It is only worth pursuing as a design reference plus a small reusable core, not as an installed bundle.

Architecture fit

• The bundle's value is Symfony container wiring: a bundle class, a DI extension that builds a configuration tree, service definitions for the toggle operator/collection, a Twig extension, and config-file-driven toggle definitions. None of that machinery exists in Laravel — no bundle registration, no compiler passes, no TreeBuilder, no service tagging.
• The framework-agnostic part is the underlying qandidate/toggle library (toggle model, conditions/context, operator). That is genuinely portable to Laravel behind a service provider; the bundle wrapper is not.
• Net: architecture fit poor as a dependency, fair as a pattern. Expect to re-implement, not integrate.

Integration feasibility

• Three viable paths, in descending order of preference:
  1. Build native on the Laravel side (Laravel Pennant is the first-party option) and skip this package entirely. Lowest total cost, best long-term support story.
  2. Port the bundle's semantics: depend on qandidate/toggle core, write a ~150–300 LOC FeatureToggleServiceProvider that binds the operator as a singleton, hydrates toggles from config/features.php, and exposes a facade plus a Blade directive. Reuse the bundle's config schema as our spec so behaviour matches.
  3. Fork and vendor-patch the bundle only if the host platform turns out to be Symfony and version constraints block installation.
• Feasibility of path 2 is high: the toggle core is small, has no framework coupling, and MIT licensing permits a fork. Effort is measured in engineer-days, not weeks.

Technical risk

• Abandonment (high): 0 dependents and a low star count indicate no production user base to absorb upgrade work. Upstream Qandidate Labs projects have been effectively dormant for years; assume no fixes, no security response, no Symfony/PHP version catch-up.
• Version ceiling (high): bundles of this vintage typically pin Symfony 2.x/3.x and PHP 5.6/7.x constraints, which will not resolve against modern PHP 8.x or Symfony 5+/Laravel 10+. Verify composer.json constraints before anything else — this is a go/no-go gate.
• Release metadata is suspect (medium): a "last release" dated 2026-08-09 is anomalous for a dormant repository. Treat version and release data as unreliable and confirm directly on Packagist/GitHub tags rather than from this feed.
• Semantics risk (medium): config-file-driven toggles require a deploy to flip a flag unless a mutable storage adapter is wired in. That undercuts the main operational benefit of feature flags and is a common source of disappointment.
• Blast-radius risk (medium): toggle evaluation sits in request paths. Its failure behaviour (fail-open vs fail-closed) is a product decision, not just a technical one, and must be specified explicitly.

Key questions

1. What is the actual host framework and version for the target service — Laravel, Symfony, or mixed? This determines whether the package is even a candidate.
2. Do we need static, deploy-time toggles, or runtime-flippable toggles with targeting (user/segment/percentage)? Only the latter justifies this stack at all.
3. Which PHP and framework constraints must resolve? Does composer require succeed without --ignore-platform-reqs?
4. Who owns the toggle lifecycle — creation, naming convention, and removal? Flags without an owner become permanent branches.
5. Is a maintained alternative (Pennant, Unleash SDK, OpenFeature-compatible provider) acceptable, or is there a hard constraint favouring this package?
6. What is the required behaviour when the toggle source is unavailable — serve the new path or the old one?

Integration Approach

Stack fit

• Laravel (likely case): do not install the bundle. Install qandidate/toggle core if we want its condition/context model, wrap it in a service provider, and expose Feature::active('flag') plus an @feature Blade directive. Register a singleton operator bound to a config-backed or cache-backed collection.
• Symfony: the bundle is the intended fit, but only on a version-compatible release line. Confirm the constraint matrix first; if incompatible, fork (the bundle surface is small — class, extension, config tree, Twig extension — and straightforward to forward-port).
• Keep the bundle's YAML config shape as our config schema either way; it preserves familiarity and makes a later Symfony port trivial.

Migration path

1. Inventory existing conditionals (if (config(...)), env checks, isActive calls) and classify each as release toggle, experiment, ops/kill-switch, or permission — they have different lifetimes and different removal owners.
2. Introduce an in-app seam first: a ToggleResolver interface with a config-file implementation. This decouples us from any vendor choice and makes the next step reversible.
3. Add the qandidate adapter behind that interface; register it in a service provider; add contract tests covering condition evaluation, default/missing flags, and error behaviour.
4. Shadow-run old and new resolution paths in staging, logging divergences, then cut over flag-by-flag — never all at once.
5. Retire the old checks and schedule deletion of release toggles; keep ops/kill-switch flags permanently with explicit owners.

Compatibility

• Verify: PHP version support, Symfony ContainerBuilder/Extension API usage, Twig extension signature (pre-namespacing Twig 1/2 classes break on Twig 3), PSR-11 vs container-interop, and whether the transitive qandidate/toggle dependency itself resolves on current PHP.
• If any of the above fails, the fork-and-patch path adds a Composer vcs/path repository and an internal maintenance commitment — factor that into the decision now, not after adoption.

Sequencing

• Week 0: constraint spike (half a day) — attempt install, inspect composer.json, read the DI extension. This single spike resolves most of the open questions.
• Week 1: build the ToggleResolver seam + config implementation in the app; ship with zero behaviour change.
• Week 2: adapter and contract tests; shadow-run in staging.
• Week 3+: progressive cutover, then a written decision on whether to keep a fork alive or migrate to a maintained provider.

Operational Impact

Maintenance

• Assume self-maintenance. Budget an owner for the adapter/fork: dependency bumps, PHP upgrades, and Twig/container API drift. A vendored fork is cheap to hold but has a real carrying cost in upgrade cycles.
• MIT licence makes forking safe; it does not make the fork maintained. Any fork must be explicitly registered in our dependency-risk register with a review date.

Support

• No vendor, dormant issue tracker, no guaranteed security response. Escalation path is internal engineering only. This is acceptable for a low-blast-radius internal flag layer, unacceptable if toggles gate payments, entitlements, or compliance behaviour.

Scaling

• Lookup cost per evaluation is trivial (in-memory collection, hash-style access). The scaling concern is config distribution and consistency, not CPU: config-file toggles require a deploy per change and can differ between web and queue workers if cache isn't cleared. Use a shared store (Redis/DB) or a single deployment-time cache warm step, and cache the resolved flag set per request/job rather than per call.
• A remote/Redis adapter introduces a network hop per evaluation; batch or memoize per request. At high fan-out, prefer one resolution per request lifecycle.

Failure modes

• Toggle source unavailable: must be specified per flag (fail_open vs fail_closed); default to the last known safe value and log loudly.
• Stale flags: the dominant real-world failure. Unremoved toggles become untested dead branches and combinatorial test surface. Mitigate with mandatory owner + expiry metadata and a CI lint that fails on expired flags.
• Config cache staleness / deploy skew: old and new code paths must both remain correct, or a rolling deploy will surface broken behaviour mid-rollout.
• Silent misconfiguration: a typo'd flag name evaluating to false is indistinguishable from an intentional off state. Fail loudly on unknown-flag lookups in non-production.
• Fork drift: if we fork and stop bumping, the PHP/framework upgrade eventually blocks the host application's upgrade. Track it.

Ramp-up

• Conceptually low: feature flags are well understood, and the library surface is small. A mid-level engineer can be productive on the adapter in under a day.
• The real ramp cost is organisational, not technical: naming conventions, who may flip production flags, whether flips need review, and the removal discipline. Document this before enabling the first production flag.
• Estimated effort for the recommended path (Laravel, native/Pennant or thin qandidate adapter): 1–2 engineer-days for the spike and seam, 3–5 days including tests, an admin surface, and rollout — materially less than owning a fork long-term.