Parameter Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require danilovl/parameter-bundle
   

   Ensure Danilovl\ParameterBundle\ParameterBundle::class is registered in config/bundles.php.

2. Basic Usage: Inject the ParameterServiceInterface into your service/controller:

   use Danilovl\ParameterBundle\Interfaces\ParameterServiceInterface;
   
   public function __construct(private ParameterServiceInterface $parameterService) {}
   
   // Access a parameter (e.g., `app.some_key` from config/packages/app.yaml)
   $value = $this->parameterService->get('some_key');
   

3. First Use Case: Replace hardcoded config values (e.g., API keys, feature flags) with dynamic parameters:

   # config/packages/app.yaml
   parameters:
       app.api_key: 'your_api_key_here'
       app.feature_flags:
           new_ui: true
   

   Access them in code:

   $apiKey = $this->parameterService->get('app.api_key');
   $newUIEnabled = $this->parameterService->get('app.feature_flags.new_ui');
   

Implementation Patterns

Common Workflows

1. Nested Parameter Access: Use the delimiter (default: ::) to traverse nested structures:

   // config/packages/app.yaml
   parameters:
       app.settings:
           timeout: 30
           retries: 3
   
   // Access nested values
   $timeout = $this->parameterService->get('app.settings.timeout'); // 30
   

2. Environment-Specific Parameters: Override parameters per environment (e.g., config/packages/dev/app.yaml):

   parameters:
       app.debug: true
   

   Access via:

   $debugMode = $this->parameterService->get('app.debug'); // true in dev
   

3. Validation and Fallbacks: Provide default values or validate types:

   $timeout = $this->parameterService->get('app.settings.timeout', 10); // Fallback to 10
   $isActive = (bool) $this->parameterService->get('app.feature_flags.enabled', false);
   

4. Twig Integration: Pass the service to Twig templates for dynamic UI logic:

   {% if parameterService.get('app.feature_flags.new_ui') %}
       <div class="new-ui">...</div>
   {% endif %}
   

Integration Tips

• Dependency Injection: Prefer constructor injection for critical parameters (e.g., API keys) to avoid runtime errors.
• Configuration Validation: Use Symfony’s validator to validate parameter structures early (e.g., in config/packages/validator.yaml):

  services:
      App\Validator\ParameterValidator:
          tags: [validator.constraint_validator]
  

• Parameter Groups: Organize parameters by domain (e.g., app., mail., db.) to avoid collisions.

Gotchas and Tips

Pitfalls

1. Delimiter Conflicts: Avoid using the delimiter (:: by default) in parameter keys. Customize the delimiter in config if needed:

   danilovl_parameter:
       delimiter: '.'
   

   Now use app.settings.timeout instead of app::settings::timeout.

2. Caching Headaches: Parameters are cached by default. Clear the cache after changing config/packages/*.yaml:

   php bin/console cache:clear
   

3. Missing Parameters: Unset parameters return null. Always provide fallbacks or validate existence:

   if ($this->parameterService->has('app.some_key')) {
       // Safe to use
   }
   

4. Type Safety: The service returns raw values (e.g., strings for booleans). Cast explicitly:

   $enabled = (bool) $this->parameterService->get('app.enabled', 'false');
   

Debugging

• Parameter Dump: Create a debug command to inspect all parameters:

  use Danilovl\ParameterBundle\Interfaces\ParameterServiceInterface;
  
  class DebugParametersCommand extends Command {
      public function __construct(private ParameterServiceInterface $parameterService) {}
  
      protected function execute(InputInterface $input, OutputInterface $output): int {
          $parameters = $this->parameterService->getAll();
          $output->writeln(json_encode($parameters, JSON_PRETTY_PRINT));
          return Command::SUCCESS;
      }
  }
  

  Register it in config/services.yaml:

  services:
      App\Command\DebugParametersCommand:
          tags: ['console.command']
  

• Environment Mismatches: Verify parameters are loaded from the correct environment file (e.g., dev, prod). Use:

  php bin/console debug:config danilovl_parameter
  

Extension Points

1. Custom Parameter Sources: Extend the bundle by implementing ParameterSourceInterface to load parameters from external sources (e.g., databases):

   use Danilovl\ParameterBundle\Interfaces\ParameterSourceInterface;
   
   class DatabaseParameterSource implements ParameterSourceInterface {
       public function load(): array {
           return $this->db->fetchAll('SELECT * FROM app_parameters');
       }
   }
   

   Register the source in config/packages/parameter.yaml:

   danilovl_parameter:
       sources:
           - '@database_parameter_source'
   

2. Parameter Events: Listen for parameter changes (e.g., after config reload):

   use Danilovl\ParameterBundle\Event\ParameterLoadedEvent;
   
   class ParameterListener {
       public function onParameterLoaded(ParameterLoadedEvent $event) {
           // Log or process loaded parameters
       }
   }
   

   Bind the listener in config/services.yaml:

   services:
       App\EventListener\ParameterListener:
           tags:
               - { name: 'kernel.event_listener', event: 'danilovl.parameter.loaded' }
   

3. Parameter Validation: Add custom validation rules for parameters:

   use Symfony\Component\Validator\Constraints as Assert;
   
   $builder->add('app.api_key', new Assert\NotBlank(), [
       'message' => 'API key cannot be blank',
   ]);