Simple Config Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require barth/simple-config-bundle
   

2. Enable Bundle: Add to config/bundles.php:

   Barth\SimpleConfigBundle\BarthSimpleConfigBundle::class => ['all' => true],
   

3. Import Routes: Add to config/routes.yaml:

   barth_simpleconfig:
       resource: "@BarthSimpleConfigBundle/Controller/"
       type: annotation
       prefix: /admin/config
   

4. First Use Case: Access /admin/config to see a form for editing bundle configurations. The bundle automatically detects and exposes configuration options from other bundles (e.g., twitter_client_id, twitter_client_secret).

Implementation Patterns

Workflow for Configuration Management

1. Expose Configurations: The bundle scans for bundle configurations defined in Resources/config/config.yaml (or similar) and generates a form for each. Example:

   # AcmeTwitterBundle/Resources/config/config.yaml
   parameters:
       twitter_client_id: ~
       twitter_client_secret: ~
   

   The form will render fields for these parameters.

2. Admin Interface:

   • Navigate to /admin/config to view/edit configurations.
   • Use the "Save" button to persist changes. The bundle writes overrides to config/packages/override.yaml (or a custom path).

3. Integration with Existing Configs:

   • Override default configurations by extending config/packages/override.yaml:

     parameters:
         twitter_client_id: 'your_id_here'
         twitter_client_secret: 'your_secret_here'
     

   • The bundle merges these overrides with default configs at runtime.

4. Dynamic Configuration:

   • For dynamic values (e.g., database-driven configs), extend the bundle by implementing Barth\SimpleConfigBundle\Config\ConfigProviderInterface and register it as a service.

5. Accessing Configs in Code: Use Symfony’s ParameterBag or ContainerInterface to access updated values:

   $clientId = $this->getParameter('twitter_client_id');
   

Gotchas and Tips

Pitfalls

1. Configuration Merging:

   • Overrides in override.yaml replace default values, not merge them. Use parameters or framework keys carefully to avoid unintended overwrites.
   • Example: If twitter_client_id is null in defaults, it will be set to null in overrides unless explicitly defined.

2. Caching:

   • The bundle caches configuration forms. Clear the cache (php bin/console cache:clear) after adding new config files to Resources/config/config.yaml.

3. Security:

   • The admin interface is not authenticated by default. Protect it with Symfony’s security system:

     # config/routes.yaml
     barth_simpleconfig:
         resource: "@BarthSimpleConfigBundle/Controller/"
         type: annotation
         prefix: /admin/config
         requirements:
             _role: ROLE_ADMIN
     

4. Bundle Compatibility:

   • Only bundles with explicit configuration files (e.g., config.yaml) are exposed. Bundles using Extension classes (e.g., load() methods) may not appear in the UI.
   • Workaround: Manually define a config.yaml in your bundle’s Resources/config/ directory.

5. File Permissions:

   • Ensure config/packages/override.yaml is writable by the web server user:

     chmod 644 config/packages/override.yaml
     

Tips

1. Custom Override Path: Change the override file location by configuring the bundle:

   # config/packages/barth_simple_config.yaml
   barth_simple_config:
       override_file: '%kernel.project_dir%/config/custom_overrides.yaml'
   

2. Field Customization: Override form types for specific parameters by creating a service tagged as barth_simple_config.form.type:

   services:
       app.twitter_client_id_type:
           class: App\Form\Type\TwitterClientIdType
           tags:
               - { name: barth_simple_config.form.type, parameter: twitter_client_id }
   

3. Validation: Add validation rules to override.yaml by extending the bundle’s form builder. Example:

   // src/Form/Extension/ConfigExtension.php
   namespace App\Form\Extension;
   
   use Barth\SimpleConfigBundle\Form\Type\ConfigType;
   use Symfony\Component\Form\AbstractTypeExtension;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class ConfigExtension extends AbstractTypeExtension
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder->add('twitter_client_id', TextType::class, [
               'constraints' => [new NotBlank(), new Length(['max' => 50])],
           ]);
       }
   
       public function getExtendedType()
       {
           return ConfigType::class;
       }
   }
   

4. Debugging:

   • Enable debug mode to see raw configuration data:

     // config/packages/dev/barth_simple_config.yaml
     barth_simple_config:
         debug: true
     

   • Check the override.yaml file directly for errors (e.g., YAML syntax).

5. Local Development: Use environment variables for sensitive data (e.g., twitter_client_secret) and exclude them from the UI by prefixing with _ (e.g., _twitter_client_secret). The bundle ignores parameters starting with _.