Feature Flags Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require 21torr/feature-flags
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       FeatureFlagsBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console feature-flags:install
   

   Edit config/packages/feature_flags.yaml to define your flags:

   feature_flags:
       flags:
           new_ui: true
           experimental_search: false
   

3. First Use Case Check a flag in a controller:

   use FeatureFlagsBundle\FeatureFlags;
   
   class HomeController extends AbstractController {
       public function index(FeatureFlags $featureFlags) {
           if ($featureFlags->isEnabled('new_ui')) {
               return $this->render('new_ui.html.twig');
           }
           return $this->render('old_ui.html.twig');
       }
   }
   

Implementation Patterns

Core Workflows

1. Flag Management

   • Runtime Overrides: Use environment variables to override flags:

     # .env
     FEATURE_FLAGS_NEW_UI=true
     

   • Database Backing: Extend the FlagProvider to fetch flags from a DB:

     class DatabaseFlagProvider implements FlagProviderInterface {
         public function getFlags(): array {
             return Flag::query()->pluck('enabled', 'name')->toArray();
         }
     }
     

2. Dependency Injection

   • Inject FeatureFlags into services, controllers, or middleware:

     public function __construct(private FeatureFlags $featureFlags) {}
     

3. Twig Integration Use the Twig extension for templates:

   {% if feature_flags.isEnabled('experimental_search') %}
       <div class="experimental-search">
           {{ include('experimental_search.html.twig') }}
       </div>
   {% endif %}
   

4. Middleware for Routing Dynamically route based on flags:

   $router->add('/admin', AdminController::class)
       ->withRequirement('feature_flags.admin_access', true);
   

Advanced Patterns

• A/B Testing: Combine flags with user segments (e.g., user_id % 2 == 0).
• Gradual Rollouts: Use flags with percentages:

  feature_flags:
      new_checkout: { enabled: 30 } # 30% rollout
  

  Extend the FlagProvider to handle numeric values.

Gotchas and Tips

Pitfalls

1. Caching Headaches

   • Flags are cached by default. Clear cache after changes:

     php bin/console cache:clear
     

   • Disable caching in feature_flags.yaml for development:

     feature_flags:
         cache: false
     

2. Namespace Collisions

   • Ensure flag names are unique (e.g., app.new_ui vs. new_ui).

3. Environment Overrides

   • Prefix env vars with FEATURE_FLAGS_ (e.g., FEATURE_FLAGS_NEW_UI).
   • Undefined env vars default to false.

Debugging

• Log Flag Evaluations Enable debug mode in feature_flags.yaml:

  feature_flags:
      debug: true
  

  Check logs for flag resolution details.

• Test Flag Isolation Use FeatureFlags::setFlag() in tests:

  $featureFlags->setFlag('new_ui', true);
  $this->assertTrue($featureFlags->isEnabled('new_ui'));
  

Extension Points

1. Custom Providers Implement FlagProviderInterface for dynamic sources (e.g., Redis, API):

   class ApiFlagProvider implements FlagProviderInterface {
       public function getFlags(): array {
           return json_decode(file_get_contents('https://api.example.com/flags'), true);
       }
   }
   

   Register in feature_flags.yaml:

   feature_flags:
       providers:
           - FeatureFlagsBundle\Provider\YamlFlagProvider
           - App\Provider\ApiFlagProvider
   

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

   use FeatureFlagsBundle\Event\FlagUpdatedEvent;
   
   public static function getSubscribedEvents(): array {
       return [
           FlagUpdatedEvent::class => 'onFlagUpdated',
       ];
   }
   

3. Validation Add validation rules to flags in feature_flags.yaml:

   feature_flags:
       flags:
           payment_gateway:
               enabled: true
               validator: 'is_string|max:255'