Feature Flags Laravel Package

Getting Started

1. Install the package:

   composer require ylsideas/feature-flags:^3.0
   

2. Publish config:

   php artisan vendor:publish --provider="YlsIdeas\FeatureFlags\FeatureFlagsServiceProvider" --tag=config
   

   This creates config/features.php, where you define feature flags (e.g., 'my-feature' => true).

3. First use:
   Check feature status in code:

   use YlsIdeas\FeatureFlags\Facades\Features;
   
   if (Features::accessible('my-feature')) {
       // Enable new behavior
   }
   

4. Explore docs:
   Read the official docs — especially the Features, Gate, Pipeline, and Repositories sections.

Implementation Patterns

• Feature Flag Definitions:
  Define flags in config/features.php or dynamically via the Features::register() method (e.g., Features::register('feature-name')->default(false)).

• Route Guarding:
  Use the feature middleware in routes/web.php:

  Route::get('/new-dashboard', fn () => ...)->middleware('feature:dashboard-v2');
  

• ** Blade Integration**:
  Use @feature / @elsefeature / @endfeature directives:

  @feature('beta-ui')
      <x-beta-ui />
  @elsefeature
      <x-classic-ui />
  @endfeature
  

• Schedule Task Filtering:
  Wrap console commands in Feature::whenFeatureIsAccessible():

  Features::whenFeatureIsAccessible('nightly-report', function () {
      $this->call('report:nightly');
  });
  

• Query Builder Enhancements:
  Conditionally apply scopes using mixins:

  $users = User::whenFeatureIsAccessible('premium-segment')
      ->where('tier', 'premium')
      ->get();
  

• Testing:
  Use Features::fake() to simulate flag states in tests:

  Features::fake(['my-feature' => true]);
  $this->get('/path-with-feature')->assertSuccessful();
  

• Gate Driver:
  Use Features::gate('feature-name') in policies or middleware to abstract access logic.

Gotchas and Tips

• Null vs. Boolean Caching:
  v3.0.1+ forces cache results to boolean — but if you wrote custom repositories or gate handlers, ensure they return bool, not null, to avoid unexpected behavior.

• Pipeline Order Matters:
  Features resolve using a pipeline of repositories (e.g., cache, database, in_memory). Ensure order in config/features.php reflects priority: fallback chain matters!

• In-Memory Config Overrides:
  Changes to features.php require php artisan config:clear — it’s not auto-reloaded in production.

• Middleware Caveat:
  The feature middleware only blocks access when the flag is off. Always combine with auth/authorization for robust control.

• Maintenance Mode + Flags:
  Feature flags integrate with Laravel’s maintenance mode — use Features::maintenance() to gate controlled rollouts during outages.

• Debugging:
  Use Features::all() (for debugging only!) or the built-in php artisan feature:state command to inspect runtime flag states.

• Extensibility:
  Create custom repository drivers by implementing Repository interface and register via Features::extend('custom', fn () => new CustomRepo()) in FeatureServiceProvider.

• Upgrade Path:
  Version 3 maintains API compatibility with v2 (type hints only); v2 → v3 is trivial, but v1 users must follow the v1→v2 upgrade guide due to pipeline/gateway rewrite.

• Facade DocBlocks:
  Auto-generated facade docs may lag — run composer lint and composer analyse during development to ensure IDE hints stay accurate.