Parameter Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ardent/parameter-bundle
   

   Add the bundle to your config/bundles.php:

   Ardent\ParameterBundle\ArdentParameterBundle::class => ['all' => true],
   

2. Database Migration Run the bundle’s migration to create the parameters table:

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

   (Note: The bundle provides a default migration at vendor/ardent/parameter-bundle/migrations/VersionYYYYMMDDHHMMSS.php.)

3. First Use Case Define a parameter in a service or controller:

   use Ardent\ParameterBundle\Parameter\ParameterManager;
   
   class MyService {
       public function __construct(private ParameterManager $parameterManager) {}
   
       public function getSiteName() {
           return $this->parameterManager->get('site.name', 'Default Site');
       }
   }
   

   Access it via the CLI:

   php bin/console ardent:parameter:set site.name "My Awesome Site"
   

Implementation Patterns

Core Workflows

1. Parameter Management

   • Setting/Updating: Use the CLI or inject ParameterManager:

     $this->parameterManager->set('app.max_retries', 5);
     

   • Fetching: Default values fall back gracefully:

     $timeout = $this->parameterManager->get('http.timeout', 30); // Returns 30 if 'http.timeout' DNE
     

2. Environment-Specific Parameters Leverage the environment column (default: prod) to scope parameters:

   $this->parameterManager->get('feature.flags.new_ui', false, 'staging');
   

3. Validation & Type Safety Use the ParameterManager::getWithValidation() method:

   $this->parameterManager->getWithValidation(
       'api.key',
       'string',
       ['min' => 10, 'max' => 255]
   );
   

4. Caching Layer Enable Redis/Memcached caching via config/packages/ardent_parameter.yaml:

   ardent_parameter:
       cache: true
       cache_pool: cache.app
   

Integration Tips

• Symfony Config Integration Override default parameters in config/packages/ardent_parameter.yaml:

  ardent_parameter:
      default_environment: '%env(APP_ENV)%'
  

• Event Listeners Trigger actions on parameter updates via ParameterUpdatedEvent:

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

  Register in services.yaml:

  services:
      App\EventListener\ParameterUpdateListener:
          tags:
              - { name: 'kernel.event_listener', event: 'ardent.parameter.updated' }
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity Parameter names are case-sensitive ('API_KEY' ≠ 'api_key'). Use constants or a naming convention (e.g., snake_case).

2. Default Environment If default_environment is unset, parameters default to null in the environment column, making them global (applicable to all environments). Explicitly set it:

   ardent_parameter:
       default_environment: '%env(APP_ENV)%'
   

3. Migration Conflicts If you’ve manually created a parameters table, drop it first before running the bundle’s migration to avoid column conflicts.

4. Caching Stale Data Clear the cache after bulk updates:

   php bin/console cache:clear
   

   Or programmatically:

   $this->parameterManager->clearCache();
   

Debugging

• Parameter Existence Check Use has() to avoid silent fallbacks:

  if ($this->parameterManager->has('critical.config')) {
      // Handle existence
  }
  

• Query Logging Enable Doctrine debug mode to inspect SQL queries:

  # config/packages/dev/doctrine.yaml
  doctrine:
      dbal:
          logging: true
          profiling: true
  

Extension Points

1. Custom Parameter Types Extend Ardent\ParameterBundle\Entity\Parameter for serialized data (e.g., JSON):

   // src/Entity/CustomParameter.php
   use Ardent\ParameterBundle\Entity\Parameter;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class CustomParameter extends Parameter {
       #[ORM\Column(type: 'json', nullable: true)]
       private ?array $data = null;
   
       // Getters/setters...
   }
   

   Update the bundle’s ParameterRepository to handle the new type.

2. Parameter Groups Add a group column to the parameters table and filter queries:

   $this->parameterManager->getAllByGroup('payment');
   

   (Requires custom repository logic.)

3. Audit Logging Use Doctrine lifecycle callbacks to log changes:

   #[ORM\PreUpdate]
   public function onPreUpdate() {
       $this->setUpdatedAt(new \DateTime());
       // Log to a separate table...
   }