Settings Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle via Composer:

   composer require bluesteel42/settings-bundle
   

   Register the bundle in AppKernel.php:

   $bundles[] = new BlueSteel42\SettingsBundle\BlueSteel42SettingsBundle();
   

2. First Use Case Define a setting in a YAML file (default backend) under %kernel.root_dir%/Resources/config/settings.yml:

   app:
       debug: true
       max_retries: 3
   

   Access settings in a controller or service:

   $settings = $this->get('bluesteel42_settings.settings');
   $debugMode = $settings->get('app/debug'); // Returns `true`
   

3. Where to Look First

   • Configuration: config.yml for backend selection.
   • Storage: %kernel.root_dir%/Resources/config/settings.yml (default).
   • Service: bluesteel42_settings.settings for runtime access.

Implementation Patterns

Core Workflows

1. Defining Settings Use YAML/XML files or Doctrine DBAL for structured configuration:

   # config/settings.yml
   features:
       notifications: true
       analytics: false
   

   Access via:

   $this->get('bluesteel42_settings.settings')->get('features/notifications');
   

2. Dynamic Backend Switching Override the backend in config.yml for different environments:

   # config_prod.yml
   bluesteel42_settings:
       backend: doctrinedbal
       table_name: app_settings
   

3. Validation and Defaults Set defaults in code or config files:

   $settings->set('app/timeout', 30, ['default' => 60]); // Falls back to 60
   

4. Integration with Services Inject the Settings service into controllers/services:

   use BlueSteel42\SettingsBundle\Settings\SettingsInterface;
   
   class MyService {
       public function __construct(SettingsInterface $settings) {
           $this->settings = $settings;
       }
   }
   

5. Environment-Specific Overrides Use separate config files (e.g., settings_dev.yml, settings_prod.yml) and merge them:

   # config.yml
   bluesteel42_settings:
       files:
           - "%kernel.root_dir%/config/settings.yml"
           - "%kernel.root_dir%/config/settings_%kernel.environment%.yml"
   

Gotchas and Tips

Pitfalls

1. File Permissions Ensure the storage directory (e.g., Resources/config/) is writable by the web server:

   chmod -R 775 %kernel.root_dir%/Resources/config/
   

2. Doctrine DBAL Schema If using doctrinedbal, manually create the table (no migrations are provided):

   CREATE TABLE app_settings (
       key VARCHAR(255) PRIMARY KEY,
       value TEXT,
       type VARCHAR(50)
   );
   

3. Caching Quirks Changes to YAML/XML files require a cache clear to reflect:

   php bin/console cache:clear
   

4. Key Collisions Avoid duplicate keys across files; later files overwrite earlier ones.

Debugging

• Check Backend Logs: Enable Symfony’s profiler to inspect bluesteel42_settings events.
• Validate Config: Use php bin/console debug:config bluesteel42_settings to verify settings.

Extension Points

1. Custom Backends Implement BlueSteel42\SettingsBundle\Settings\Backend\BackendInterface for new storage (e.g., Redis):

   class RedisBackend implements BackendInterface {
       public function load() { /* ... */ }
       public function save($data) { /* ... */ }
   }
   

   Register via config.yml:

   bluesteel42_settings:
       backend: redis
   

2. Event Listeners Subscribe to settings.load and settings.save events for pre/post-processing:

   services:
       app.settings_listener:
           class: AppBundle\EventListener\SettingsListener
           tags:
               - { name: kernel.event_listener, event: settings.load, method: onLoad }
   

3. Type Safety Enforce types in settings (e.g., booleans, integers) via validation rules:

   $settings->set('app/enabled', true, ['type' => 'bool']);