Feature Flag Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dknx01/feature-flag-bundle
   

   Add to config/app.php under providers:

   Dknx\FeatureFlagBundle\FeatureFlagBundle::class,
   

2. First Flag Definition Define a flag in config/featureflags.php (auto-generated on first run):

   return [
       'flags' => [
           'new_ui' => [
               'enabled' => false,
               'description' => 'Enable the new user interface',
           ],
       ],
   ];
   

3. First Usage

   use Dknx\FeatureFlagBundle\FeatureFlagManager;
   
   $flagManager = app(FeatureFlagManager::class);
   if ($flagManager->isEnabled('new_ui')) {
       // Show new UI
   }
   

4. Environment-Specific Flags Use featureflags_[env].php (e.g., featureflags_production.php) for environment overrides.

Implementation Patterns

Core Workflows

1. Flag Evaluation

   // Basic check
   $isEnabled = $flagManager->isEnabled('flag_name');
   
   // With user context (if using user-based flags)
   $isEnabled = $flagManager->isEnabled('flag_name', $user);
   

2. Dynamic Flag Updates

   // Runtime updates (e.g., via admin panel)
   $flagManager->setEnabled('flag_name', true);
   

3. Group-Based Flags

   // Define in config:
   'flags' => [
       'premium_feature' => [
           'enabled' => true,
           'groups' => ['premium_users'],
       ],
   ],
   // Check in code:
   $flagManager->isEnabled('premium_feature', $user);
   

4. A/B Testing

   // Define in config:
   'flags' => [
       'ab_test_variant' => [
           'enabled' => true,
           'variants' => ['A', 'B'],
           'strategy' => 'random', // or 'user_hash', 'cookie'
       ],
   ],
   // Get variant:
   $variant = $flagManager->getVariant('ab_test_variant', $user);
   

Integration Tips

• Service Container Binding Bind the manager to your container for cleaner usage:

  $this->app->bind('featureFlag', function ($app) {
      return $app->make(FeatureFlagManager::class);
  });
  

  Then inject via constructor:

  public function __construct(private FeatureFlagManager $flagManager) {}
  

• Middleware for Route-Based Flags

  public function handle($request, Closure $next)
  {
      if (!$this->flagManager->isEnabled('admin_panel')) {
          abort(403);
      }
      return $next($request);
  }
  

• Event Listeners Listen for flag changes (e.g., log updates):

  public function handle(FlagUpdatedEvent $event)
  {
      Log::info("Flag {$event->getFlagName()} updated to {$event->isEnabled()}");
  }
  

Gotchas and Tips

Common Pitfalls

1. Caching Issues

   • Flags are cached by default. Clear cache after runtime updates:

     php artisan cache:clear
     

   • Disable caching in config/featureflags.php if needed:

     'cache_enabled' => false,
     

2. User Context Overrides

   • Ensure user objects passed to isEnabled() implement getId() or getEmail() as required by the bundle.

3. Configuration Merging

   • Environment-specific configs (featureflags_[env].php) are merged after the base config. Overrides must be explicit.

4. Variant Strategies

   • Custom strategies require implementing Dknx\FeatureFlagBundle\Strategy\VariantStrategyInterface. Default strategies (random, user_hash) may not suit all use cases.

Debugging Tips

• Enable Logging Set debug to true in config/featureflags.php to log flag evaluations:

  'debug' => env('APP_DEBUG', false),
  

• Check Flag Existence Use hasFlag() to avoid runtime errors:

  if ($flagManager->hasFlag('non_existent_flag')) {
      // Safe to check
  }
  

• Validate Config Run:

  php artisan featureflag:validate
  

  To catch config syntax errors early.

Extension Points

1. Custom Strategies Register a new variant strategy:

   $flagManager->addVariantStrategy('custom', new CustomStrategy());
   

2. Flag Providers Extend functionality by creating a custom provider:

   class DatabaseFlagProvider implements FlagProviderInterface
   {
       public function getFlag(string $name): ?array
       {
           // Fetch from DB
       }
   }
   

   Register in config/featureflags.php:

   'providers' => [
       'database',
       // Your custom provider
   ],
   

3. Event Customization Extend or override events (e.g., FlagUpdatedEvent) to trigger custom logic.

4. API for Admin Panels Use the built-in API endpoints (if enabled) or create a custom controller to manage flags dynamically:

   // Example route:
   Route::post('/admin/flags/{name}', [FlagController::class, 'update']);