Kdb Parameters Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle via Composer:

   composer require caragk/kdb-parameters-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       CaraGk\KDBParametersBundle\KDBParametersBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config (if needed) and adjust config/packages/kdb_parameters.yaml:

   kdb_parameters:
       default_group: 'app'  # Default group for parameters
       storage: '%kernel.project_dir%/var/kdb_parameters'  # Storage path
   

3. First Use Case: Storing a Parameter Define a parameter in a YAML file (e.g., config/kdb_parameters/app.yaml):

   # app.yaml
   app_name: "My Awesome App"
   debug_mode: true
   

   Load and use it in a controller:

   use CaraGk\KDBParametersBundle\ParameterManager;
   
   class SomeController extends AbstractController {
       public function index(ParameterManager $manager) {
           $appName = $manager->get('app_name'); // Returns "My Awesome App"
           return $this->render('index.html.twig', ['name' => $appName]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Grouped Parameter Management Organize parameters by logical groups (e.g., app, features, api). Store them in config/kdb_parameters/{group}.yaml and reference them via:

   $manager->get('group.param_name');
   

2. Dynamic Parameter Updates Use the ParameterManager to update parameters at runtime (e.g., via admin panel):

   $manager->set('debug_mode', false);
   $manager->save(); // Persists changes to storage
   

3. Environment-Specific Overrides Override parameters per environment by creating environment-specific files:

   config/kdb_parameters/
       app.yaml          # Defaults
       app.dev.yaml      # Dev overrides
       app.prod.yaml     # Prod overrides
   

   The bundle merges them automatically (later files override earlier ones).

4. Validation and Defaults Define defaults and validation rules in config/packages/kdb_parameters.yaml:

   kdb_parameters:
       groups:
           app:
               params:
                   app_name:
                       default: "My App"
                       type: string
                   debug_mode:
                       default: false
                       type: bool
   

5. Integration with Symfony’s ParameterBag Access parameters via Symfony’s ParameterBagInterface (if configured):

   # config/packages/kdb_parameters.yaml
   kdb_parameters:
       inject_into_parameter_bag: true
   

   Then use them anywhere:

   $this->getParameter('app_name');
   

Gotchas and Tips

Common Pitfalls

1. File Permissions Ensure the storage directory (var/kdb_parameters) is writable by the web server:

   chmod -R 775 var/kdb_parameters
   

   Tip: Use umask in your deployment script to avoid permission issues.

2. Caching Quirks Parameters are cached by default. Clear the cache after runtime updates:

   php bin/console cache:clear
   

   Tip: Disable caching in config/packages/kdb_parameters.yaml for development:

   kdb_parameters:
       cache: false
   

3. YAML Parsing Errors Invalid YAML in parameter files will throw exceptions. Validate files with:

   php bin/console debug:config kdb_parameters
   

4. Namespace Collisions Avoid using dots (.) in parameter names if they conflict with Symfony’s built-in parameters. Prefix custom params:

   kdb_custom_param: "value"  # Instead of custom.param
   

Advanced Tips

1. Event Listeners for Parameter Changes Subscribe to the KDBParametersUpdatedEvent to react to changes:

   // src/EventListener/ParameterUpdateListener.php
   namespace App\EventListener;
   
   use CaraGk\KDBParametersBundle\Event\KDBParametersUpdatedEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class ParameterUpdateListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               KDBParametersUpdatedEvent::class => 'onParametersUpdated',
           ];
       }
   
       public function onParametersUpdated(KDBParametersUpdatedEvent $event) {
           // Log or trigger actions when parameters change
       }
   }
   

2. Custom Storage Backends Extend the bundle to use a database or API backend by implementing CaraGk\KDBParametersBundle\Storage\StorageInterface:

   class DatabaseStorage implements StorageInterface {
       public function load(): array { /* ... */ }
       public function save(array $params): void { /* ... */ }
   }
   

   Register it in config/packages/kdb_parameters.yaml:

   kdb_parameters:
       storage: App\Storage\DatabaseStorage
   

3. Parameter Versioning Add a version field to parameter files to track changes:

   # app.yaml
   version: 2
   app_name: "Updated App"
   

   Use this to implement rollback logic or change logs.

4. Security Note Avoid storing sensitive data (e.g., passwords) in parameter files. Use Symfony’s ParameterBag or environment variables instead.