Laravel Feature Flags Laravel Package

Getting Started

This release (v1.6.1) is a patch that fixes the FeatureFlag facade alias, which previously pointed at a nonexistent plural class (FeatureFlags). If you are on v1.6.0 or earlier and your FeatureFlag::... calls or @featureflag Blade directives have been throwing "class not found" or alias resolution errors, upgrade first — nothing else changes.

Minimal setup:

1. composer require codinglabsau/laravel-feature-flags
2. Publish the config and migration: php artisan vendor:publish --provider="Codinglabs\FeatureFlags\FeatureFlagsServiceProvider"
3. Run php artisan migrate to create the feature_flags table.
4. Start with one flag and one call site, e.g. FeatureFlag::isActive('new-checkout') wrapped around a single controller branch — do not retrofit every feature at once.

Where to look first:

• config/feature-flags.php — table name, caching, and any route/middleware toggles.
• The FeatureFlag model and facade — this is the primary API surface (isActive(), activation/deactivation helpers).
• src/ for the service provider, which registers the Blade directive and middleware alias.

First use case: gate a single new feature (a route, a UI component, or a job dispatch) behind a flag, then verify you can flip it in php artisan tinker without a deploy. That "flip without deploy" loop is the entire value proposition — prove it works before expanding.

Implementation Patterns

Facade-first, with a thin wrapper. Rather than scattering FeatureFlag::isActive('x') through controllers, wrap it in a small domain helper (e.g. Features::newCheckout()) so you have one place to change when the flag is retired. This matters most at cleanup time, when you delete the flag and every call site in one commit.

Blade directives for UI toggles. Use the package's directive for view-level conditionals and the facade in PHP. Keep the same flag name in both — inconsistent naming between Blade and PHP is the most common source of "the flag is on but the button is missing" confusion.

Route middleware for whole surfaces. Register the package's middleware alias and apply it to route groups for beta endpoints. This keeps "is this available at all" separate from "which branch of the code runs," which is easier to reason about and to remove later.

Seed flags in migrations or seeders, not by hand. Every environment — local, CI, staging, prod — should start from the same known flag set with explicit default states. A flag that exists in prod but not in CI means your tests exercise a different code path than production.

Local and CI overrides. Developers should be able to force flags on locally without touching the shared database. Set the flag state in a test setUp() (or the package's fake/override mechanism) so tests are deterministic and do not depend on seeded state. Never let a test depend on the ambient value of a flag.

Artisan commands for operational flips. Toggling via the package's commands or a small custom command is preferable to editing rows by hand — it goes through the model, which keeps any cache invalidation and timestamps consistent. Wire this into your runbook so on-call can disable a bad feature without a deploy.

Retire flags aggressively. Treat every flag as having a planned deletion date. Once a feature is fully rolled out, delete the flag, the branch, and the dead code path in a single PR. Long-lived flags become invisible configuration that no one dares remove.

Gotchas and Tips

• Upgrade to v1.6.1 before debugging facade errors. Before this patch, the FeatureFlag alias resolved to a class that does not exist. If you see container or "class not found" errors from the facade, check your installed version first — this is a package bug, not your config.
• Clear the alias cache after upgrading. If you use a cached package manifest, run php artisan package:discover (and config:clear / optimize:clear in deployed environments) after composer update, or you may still be running the old broken alias map.
• Cache invalidation after out-of-band changes. If flags are cached, a direct database update (SQL editor, another service) bypasses the cache and the change will not appear until expiry or a flush. Always toggle through the model/commands, and know where the cache flush entry point is.
• Default state is the dangerous state. A missing flag row typically resolves to "inactive." If you deploy code that calls isActive('new-thing') before the row exists, the feature silently stays off — usually fine, occasionally a production incident. Decide per flag whether missing means off (rollout) or on (safety-critical path), and make that explicit.
• Config key drift. The table name and cache settings live in the published config. If you change the table name after migrating, remember the migration itself hardcodes the old name — reconcile both or you will get "table not found" only in fresh installs.
• Do not nest flag checks deeply. Two or three nested isActive() calls produce a combinatorial mess that is untestable. If you need that, you have a configuration problem, not a feature-flag problem.
• Extension points. The package is small by design. If you need percentage rollouts, per-user targeting, or an external provider, check whether the model/repository is swappable via the container before forking — binding your own implementation behind the same facade is usually cleaner than editing vendor code or wrapping the facade everywhere.
• Testing hygiene. Assert both states of every flag-guarded path. A test suite that only ever sees flags "on" will not catch the branch you ship to users when the rollout is paused.