Platform Parameter Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Bundle

   composer require ecourty/platform-parameter-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       EdouardCourty\PlatformParameterBundle\PlatformParameterBundle::class => ['all' => true],
   ];
   

2. Configure the Bundle Add basic configuration in config/packages/ecourty_platform_parameter.yaml:

   ecourty_platform_parameter:
       db_driver: doctrine # or 'array' for in-memory storage
       cache_pool: cache.app
   

3. Run Database Migrations

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

4. Define a Parameter via CLI

   php bin/console ecourty:platform-parameter:create --name="site.maintenance_mode" --type="bool" --value="false"
   

5. Access a Parameter in Code

   use EdouardCourty\PlatformParameterBundle\Parameter\ParameterManager;
   
   $maintenanceMode = $this->get(ParameterManager::class)->get('site.maintenance_mode');
   

First Use Case: Feature Flag Toggle

// Enable/disable a feature flag dynamically
$featureEnabled = $this->get(ParameterManager::class)->get('features.new_ui_enabled', false);

// In a controller
if ($featureEnabled) {
    return $this->render('new_ui.html.twig');
}

Implementation Patterns

Core Workflow: CRUD Operations

1. Create Parameters

   • CLI: php bin/console ecourty:platform-parameter:create
   • Code:

     $manager->create('site.timezone', 'string', 'UTC');
     

2. Update Parameters

   • CLI: php bin/console ecourty:platform-parameter:update
   • Code:

     $manager->update('site.timezone', 'Europe/Paris');
     

3. Fetch Parameters

   • Type-Safe Access:

     $timezone = $manager->get('site.timezone', 'UTC'); // string
     $maintenanceMode = $manager->get('site.maintenance_mode', false); // bool
     $timeout = $manager->get('api.timeout', 30); // int
     

   • Batch Fetching:

     $params = $manager->getMultiple(['site.timezone', 'api.timeout']);
     

4. Cache Management

   • Invalidate Cache:

     $manager->invalidateCache('site.*'); // Wildcard invalidation
     

   • Clear All:

     $manager->clearCache();
     

Integration Tips

1. Dependency Injection Bind ParameterManager to a service alias for easier access:

   # config/services.yaml
   services:
       App\ParameterManager: '@EdouardCourty\PlatformParameterBundle\Parameter\ParameterManager'
   

2. Twig Integration Extend Twig with a global function:

   // src/Twig/AppExtension.php
   public function getPlatformParameter(string $name, $default = null): mixed
   {
       return $this->parameterManager->get($name, $default);
   }
   

   Register in config/packages/twig.yaml:

   twig:
       globals:
           platform_parameter: '@EdouardCourty\PlatformParameterBundle\Parameter\ParameterManager'
   

3. Event-Driven Updates Listen for parameter updates to trigger side effects:

   // src/EventListener/ParameterUpdateListener.php
   public function onParameterUpdated(ParameterUpdatedEvent $event)
   {
       if ($event->getParameterName() === 'site.maintenance_mode') {
           $this->cache->clear('maintenance_page');
       }
   }
   

4. Validation Layer Add validation rules for parameters (e.g., using Symfony Validator):

   use Symfony\Component\Validator\Constraints as Assert;
   
   $constraints = new Assert\Collection([
       'value' => new Assert\Type(['type' => 'bool']),
       'min' => new Assert\GreaterThanOrEqual(['value' => 0]),
   ]);
   

Advanced Patterns

1. Parameter Namespaces Use dot notation for hierarchical parameters:

   $manager->get('features.email.notifications.enabled');
   

   Fetch all under a namespace:

   $features = $manager->getNamespace('features');
   

2. Environment-Specific Parameters Override parameters per environment via config:

   # config/packages/ecourty_platform_parameter.yaml
   ecourty_platform_parameter:
       parameters:
           site.debug: '%kernel.debug%'
           api.base_url: '%env(API_BASE_URL)%'
   

3. Parameter-Based Configuration Replace hardcoded configs with parameters:

   // Instead of:
   $maxRetries = 3;
   
   // Use:
   $maxRetries = $manager->get('api.max_retries', 3);
   

Gotchas and Tips

Pitfalls

1. Cache Invalidation Race Conditions

   • Issue: Concurrent updates may cause stale cache.
   • Fix: Use invalidateCache() after bulk updates or wrap in a transaction:

     $entityManager->beginTransaction();
     try {
         $manager->update('param1', $value1);
         $manager->update('param2', $value2);
         $manager->invalidateCache('param*');
         $entityManager->commit();
     } catch (\Exception $e) {
         $entityManager->rollBack();
         throw $e;
     }
     

2. Type Safety Gaps

   • Issue: PHP’s dynamic typing may bypass type checks.
   • Fix: Validate types explicitly:

     $value = $manager->get('param', 'default');
     if (!is_int($value)) {
         throw new \RuntimeException('Parameter must be an integer');
     }
     

3. Wildcard Cache Invalidations

   • Issue: Over-aggressive wildcards (e.g., *) may clear unrelated cache.
   • Fix: Use specific patterns like site.* or features.*.

4. Doctrine Event Conflicts

   • Issue: Custom Doctrine events may interfere with parameter updates.
   • Fix: Ensure your bundle’s listeners have higher priority:

     # config/services.yaml
     services:
         App\EventListener\ParameterListener:
             tags:
                 - { name: doctrine.event_listener, event: postUpdate, priority: 255 }
     

Debugging Tips

1. Parameter Existence Check

   if (!$manager->has('nonexistent.param')) {
       // Handle missing parameter
   }
   

2. Cache Debugging

   • Enable cache debugging in config/packages/cache.yaml:

     framework:
         cache:
             pools:
                 cache.app:
                     adapter: cache.null # Force cache misses
     

   • Check cached parameters:

     php bin/console cache:pool:list
     php bin/console cache:pool:clear cache.app
     

3. CLI Verbosity Use -v or -vv flags for detailed output:

   php bin/console ecourty:platform-parameter:list -vv
   

Configuration Quirks

1. Database Driver Switching

   • Issue: Changing db_driver from doctrine to array after initial setup requires manual data migration.
   • Fix: Export parameters first:

     php bin/console ecourty:platform-parameter:export --format=json > params.json
     

   • Then reconfigure and reimport:

     ecourty_platform_parameter:
         db_driver: array
     

     php bin/console ecourty:platform-parameter:import --format=json --file=params.json
     

2. Case Sensitivity

   • Parameter names are case-sensitive. Use consistent naming (e.g., snake_case).

3. Default Values in Config

   • Override defaults in config/packages/ecourty_platform_parameter.yaml:

     ecourty_platform_parameter:
         default_cache_ttl: 3600 # Override default TTL (300s)
         cache_prefix: 'platform_params_'
     

Extension Points

1. Custom Parameter Types Extend the ParameterType interface:

   use EdouardCourty\PlatformParameterBundle\Parameter\ParameterType;
   
   class JsonType implements ParameterType
   {
       public function getType(): string
       {
           return 'json';
       }
   
       public function serialize(mixed $value): string
       {
           return json_encode($value);
       }
   
       public function deserialize(string $value): mixed
       {
           return json_decode($value