Feature Flag Laravel Package

Technical Evaluation

Architecture fit

• The package targets Laravel applications on PHP 8.1+ and uses native attributes (#[FeaturesFlagSwitchRoute]) to declaratively gate routes and class/method execution. This is a good conceptual fit for teams already standardizing on attribute-based configuration (middleware, validation, authorization), since flag intent lives next to the code it protects rather than in a distant config file.
• Two distinct capabilities are being introduced:
  • Route switching — conditional route registration, i.e., an endpoint simply does not exist when its flag is off.
  • Class/method blocking — execution guards on services and methods.
• These have very different implementation mechanics and very different risk profiles. Route switching is a boot-time/registration-time concern; method blocking requires an interception point (container proxy, decorator, middleware, or explicit trait/base-class opt-in). PHP has no native method interception, so the enforcement mechanism is the single most important architectural question.
• Enforcement scope is likely narrower than the release notes imply. Attribute-driven blocking typically only covers code resolved through the Laravel container or invoked through the framework's HTTP/job pipeline. Direct instantiation (new Service()), static calls, third-party package internals, and long-lived Octane workers may bypass guards entirely. This should be validated, not assumed.

Integration feasibility

• Integration is likely low-ceremony: composer require, publish config, register the service provider (or rely on package discovery), and annotate targets. No schema or infrastructure changes are implied by the release notes.
• The blocker is not installation, it is verification. Before committing, a spike must confirm: (a) how flags are resolved and from where, (b) whether resolution is cached per request, (c) what happens on flag-provider failure, and (d) whether guards apply to queued jobs and console commands, not just HTTP controllers.
• Testability needs a story: flags must be overridable in PHPUnit/Pest without hitting an external provider, otherwise every flagged code path doubles the test matrix.

Technical risk

• Route caching interaction (high). If route switching evaluates flags during route registration, php artisan route:cache can freeze flag state into the compiled route file. A flag flip in production would then require a redeploy and cache rebuild, defeating the purpose of a runtime toggle. This must be confirmed as either handled or documented.
• Fail-open vs. fail-closed (high). The release notes do not state the default when a flag cannot be evaluated. Fail-open silently disables protection; fail-closed turns a provider outage into a site-wide 500. This is a product decision that must be made explicitly, not inherited from a default.
• Blast radius of class blocking (medium-high). Blocking a class that sits on a critical path (auth, payments, logging) converts a configuration mistake into an outage. Method-level guards that throw will surface as unhandled exceptions unless the package defines a typed exception and a handler.
• Performance (medium). Attribute discovery and reflection have a cost. If scanning happens per request without caching, it will show up in p95 latency, particularly on larger codebases. Needs a benchmark, not a guess.
• Semantic versioning (medium). v1.1.1 is a patch number but ships two net-new features. That signals loose semver discipline, which raises the cost of automated dependency updates and makes "safe patch upgrade" assumptions unreliable.
• API naming (low). FeaturesFlagSwitchRoute reads awkwardly (plural/compound). If this is the public attribute name, it is effectively permanent API surface. Cosmetic, but worth flagging before it spreads across the codebase.

Key questions

1. Where are flag values stored and how are they resolved (config, database, LaunchDarkly/Unleash, custom provider)? Is a provider abstraction exposed?
2. Does route switching survive route:cache and config:cache correctly, and what is the documented behavior after a flag flip without redeploy?
3. What is the enforcement mechanism for class/method blocking, and what is explicitly out of scope (static calls, new, jobs, commands, Octane)?
4. What is the default behavior when flag evaluation fails or the provider times out?
5. What exception type is raised on a blocked call, and is it handled by default?
6. Is there a per-request memoization layer, and what is the measured overhead on a representative codebase?
7. Is there any audit trail of flag evaluations for incident review?
8. Does the package support percentage rollouts / user targeting, or is it strictly boolean?
9. What is the maintainer model (single maintainer? release cadence? security policy?) and is the license compatible with our distribution model?
10. Does it support Laravel 9/10/11, and what is the PHP floor and ceiling?

Note: this assessment is derived solely from the v1.1.1 release notes. Items marked as risks are hypotheses to be confirmed in a time-boxed spike, not confirmed defects.

Integration Approach

Stack fit

• Fits any Laravel application on PHP 8.1+ that already uses attributes and a service container. No new runtime, datastore, or sidecar is implied by the release notes.
• Best value in codebases where flags are currently handled by ad-hoc if (config('features.x')) checks scattered across controllers — the package consolidates that into a declarative, greppable pattern.
• Poor fit for codebases with heavy legacy procedural code, static facades, or non-Laravel entry points, because the guards will not reach those paths.

Migration path

• Purely additive. No existing behavior changes unless an attribute is applied, so the upgrade path from "not installed" to v1.1.1 is a single dependency addition.
• Recommended adoption is incremental and reversible: install → wire a single route behind a flag → verify behavior with the flag on and off in staging → expand. Do not enable class/method blocking broadly until route-level behavior is fully understood.
• Treat existing config-based flags as a parallel system during migration. Do not attempt a flag-system migration and a feature-flag adoption in the same release.

Compatibility

• Verify explicitly against: route:cache, config:cache, optimize, Laravel Octane (long-lived workers can cache flag state across requests — a correctness issue, not just performance), queued jobs and console commands, and the test suite's flag-override mechanism.
• Check PHP and Laravel version constraints against our supported matrix before scheduling work; a floor above our oldest supported app would fragment the rollout.

Sequencing

1. Spike (1 week, non-production). Confirm enforcement mechanism, caching behavior, failure semantics, and Octane interaction. Produce a short written finding, not a demo.
2. Decide flag provider and default failure mode. This is a governance decision that must precede code.
3. Pilot: one low-risk internal route behind #[FeaturesFlagSwitchRoute]. Success criteria: flag flip changes behavior without redeploy; route cache behaves as documented.
4. Pilot: method-level blocking on one non-critical service. Success criteria: blocked call raises a handled, observable error.
5. Observability. Emit flag evaluations and block events to existing logging/metrics so incidents are diagnosable.
6. Broaden adoption with a written convention (naming, ownership, expiry) before the second team adopts it.

Operational Impact

Maintenance

• Small dependency footprint, but a young package at v1.x with a very short changelog history — expect API churn. Pin the version explicitly and review changelogs manually; do not rely on automated patch bumps given the feature-in-a-patch release.
• Attribute names become embedded across many files once adopted, so a rename in a future release is a broad, mechanical-but-non-trivial refactor. That is a real switching cost and argues for piloting before wide adoption.
• Plan for flag debt from day one: every flag needs an owner and an expiry. Without this, the package makes it easier to accumulate dead conditionals, not harder.

Support

• Documentation appears thin relative to the surface area being added. Assume the team will need an internal runbook covering: how to add a flag, how to flip one, how to remove one, what a blocked-call error looks like, and who to call.
• Single-maintainer / small-project risk should be assessed. If the package becomes load-bearing, budget for the possibility of vendoring or forking.

Scaling

• Reflection and attribute scanning scale with codebase size, not traffic, but the per-request cost still multiplies by request volume. Benchmark before broad rollout; cache aggressively if needed.
• Octane and other long-lived-worker setups require care: flag state resolved once per worker will not reflect mid-flight changes. Confirm the package's documented position here before deploying under Octane.
• Multi-tenant use cases (per-tenant flag values) are not evidenced in the release notes and should be assumed unsupported until proven otherwise.

Failure modes

• Provider unavailable → depends on the fail-open/fail-closed default; either silent loss of protection or a hard outage. Must be configured deliberately.
• Flag flipped during an incident → if route switching is baked into the route cache, the flip does nothing and responders waste minutes. High-severity operational footgun.
• Blocked critical-path class → 500s or cascading failures from a single misconfiguration.
• Route disappears → clients receive 404s rather than a controlled error, which can look like a deploy regression and misdirect incident triage.
• Stale flag in a long-lived worker → behavior diverges between workers; extremely difficult to reproduce.
• Unhandled block exception → surfaces as a generic 500 unless a typed exception and handler are wired.

Ramp-up

• Route switching: low. A developer can learn it in under an hour.
• Class/method blocking: moderate. Requires understanding container resolution, exception handling, and what the guard does not cover. Expect a half-day of team enablement plus the spike findings circulated in writing.
• Organizational ramp-up is the larger cost: flag naming conventions, ownership, review checklist ("does this PR add a flag? does it have an owner and expiry?"), and a cleanup cadence. Budget for this in the rollout plan, not after.