Config Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aaronadal/config-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   // config/bundles.php
   return [
       // ...
       Aaronadal\ConfigBundle\AaronadalConfigBundle::class => ['all' => true],
   ];
   

2. Configure Paths: Add this to config/packages/aaronadal_config.yaml (Symfony 4+):

   aaronadal_config:
       location:
           defaults: '%kernel.project_dir%/config/parameters/defaults/*.yml'
           environment: '%kernel.project_dir%/config/parameters/:env/*.yml'
   

   For Symfony 3, use config.yml under config/packages/aaronadal_config.yml.

3. First Use Case: Create a default config file at config/parameters/defaults/database.yml:

   parameters:
       database_driver: pdo_mysql
       database_host: localhost
   

   Override it for dev in config/parameters/dev/database.yml:

   parameters:
       database_host: localhost:3306
   

   Restart your dev server (php bin/console server:run). The bundle merges these files automatically.

Implementation Patterns

Workflows

1. Layered Configuration:

   • Use defaults/ for shared settings (e.g., database.yml, services.yml).
   • Override in :env/ for environment-specific tweaks (e.g., dev/, prod/).
   • Example:

     config/parameters/
     ├── defaults/
     │   ├── database.yml
     │   └── mail.yml
     └── dev/
         └── database.yml  # Overrides defaults/database.yml
     

2. Parameter Overrides:

   • Define base parameters in defaults/ (e.g., app.yml):

     parameters:
         app.debug: '%kernel.debug%'
         app.secret: '%env(APP_SECRET)%'
     

   • Override sensitive values in :env/ (e.g., prod/app.yml):

     parameters:
         app.secret: 'prod-secret-value'
     

3. Service Configuration:

   • Use the bundle to load service definitions from multiple files:

     config/services/
     ├── defaults/
     │   └── monolog.yml
     └── dev/
         └── monolog.yml  # Adds dev-specific handlers
     

   • Reference in config/services.yaml:

     imports:
         - { resource: '%kernel.project_dir%/config/services/defaults/*.yml' }
         - { resource: '%kernel.project_dir%/config/services/:env/*.yml' }
     

4. Environment-Specific Routes:

   • Load routes from config/routes/dev/*.yml or config/routes/prod/*.yml and merge them into your main routes.yaml.

Integration Tips

• Symfony Flex: If using Symfony 4/5, place config files in config/packages/ and reference them via imports in config/bundles.php.
• Caching: The bundle leverages Symfony’s cache, so changes to config files require a cache clear (php bin/console cache:clear).
• Parameter Validation: Combine with Symfony’s validator to validate merged parameters early:

  # config/validator/parameters.yml
  App\Validator\Constraints\ValidDatabaseConfig: ~
  

Gotchas and Tips

Pitfalls

1. Cache Dependency:

   • Forgetting to clear the cache after modifying config files will result in stale configurations.
   • Fix: Always run php bin/console cache:clear after changes.

2. Placeholder Limitations:

   • Only :env is supported in paths. Avoid using %kernel.root_dir% or other parameters in location keys.
   • Workaround: Use absolute paths or reference kernel.root_dir in your glob patterns manually.

3. Merge Conflicts:

   • Environment files override defaults entirely. Use explicit keys to avoid unintended overrides:

     # Bad: Overrides ALL defaults
     parameters: { ... }
     
     # Good: Only overrides specific keys
     parameters:
         database_host: override-value
     

4. Bundle Order:

   • Place AaronadalConfigBundle before bundles that depend on dynamically loaded parameters (e.g., FrameworkBundle).
   • Symfony 4+: Ensure it’s listed early in config/bundles.php.

5. File Naming:

   • Avoid naming config files with reserved names (e.g., parameters.yml to prevent conflicts with Symfony’s built-in files).

Debugging

1. Verify Loading:

   • Check loaded parameters with:

     php bin/console debug:container --parameters
     

   • Look for your custom parameters in the output.

2. Debug Paths:

   • Enable debug mode to see resolved paths:

     # config/packages/dev/aaronadal_config.yaml
     aaronadal_config:
         debug: true  # Logs loaded files (if supported)
     

3. Merge Issues:

   • Use var_dump() in a custom compiler pass to inspect merged configurations:

     // src/EventListener/ConfigDebugListener.php
     public function onKernelRequest(GetResponseEvent $event) {
         if ($event->isMasterRequest() && $this->debug) {
             var_dump($this->container->getParameter('your_custom_param'));
         }
     }
     

Extension Points

1. Custom Loaders:

   • Extend the bundle by creating a custom loader for non-YAML formats (e.g., JSON):

     // src/Loader/CustomLoader.php
     use Aaronadal\ConfigBundle\Loader\LoaderInterface;
     
     class CustomLoader implements LoaderInterface {
         public function load(string $path, string $env) {
             return json_decode(file_get_contents($path), true);
         }
     }
     

   • Register it in services.yaml:

     services:
         Aaronadal\ConfigBundle\Loader\LoaderInterface:
             class: App\Loader\CustomLoader
     

2. Pre/Post-Processing:

   • Use Symfony’s container.dumper events to modify loaded configurations:

     // src/EventSubscriber/ConfigSubscriber.php
     public static function getSubscribedEvents() {
         return [
             KernelEvents::CONTAINER_COMPILED => 'onContainerCompiled',
         ];
     }
     
     public function onContainerCompiled(ContainerCompiledEvent $event) {
         $container = $event->getContainer();
         $container->setParameter('app.processed_config', $this->process($container->getParameter('app.raw_config')));
     }
     

3. Environment Detection:

   • Override environment detection for custom environments (e.g., staging):

     # config/packages/aaronadal_config.yaml
     aaronadal_config:
         environment_detector: App\Detector\CustomEnvironmentDetector
     

     Implement App\Detector\CustomEnvironmentDetector to return your custom environment name.

Tips

1. Atomic Commits:

   • Split config changes into small, focused commits (e.g., "Add dev database config") to avoid merge conflicts.

2. Document Overrides:

   • Add comments in :env/ files to explain why a value is overridden:

     # Override for dev to use SQLite for testing
     parameters:
         database_driver: pdo_sqlite
     

3. CI/CD Integration:

   • Automate cache clearing in deployment scripts:

     # .github/workflows/deploy.yml
     - run: php bin/console cache:clear --env=prod
     

4. Backup Defaults:

   • Keep a defaults/ backup in version control (e.g., defaults.backup/) to reset overrides easily.

5. Symfony 5+:

   • For Symfony 5, use config/packages/ and ensure the bundle is auto-loaded via composer.json:

     "extra": {
         "symfony": {
             "allow-overwrite": "*"
         }
     }