Setting Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require ekyna/setting-bundle
   

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

   Ekyna\SettingBundle\EkynaSettingBundle::class => ['all' => true],
   

2. Database Migration Run the bundle’s migration to create the settings table:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case Define a setting in config/packages/ekyna_setting.yaml:

   ekyna_setting:
       settings:
           app_name: "My Awesome App"
           maintenance_mode: false
   

   Access it in a controller:

   use Ekyna\SettingBundle\Manager\SettingManager;
   
   public function index(SettingManager $settingManager)
   {
       $appName = $settingManager->get('app_name');
       return response()->json(['name' => $appName]);
   }
   

Implementation Patterns

Core Workflows

1. Dynamic Configuration Use the SettingManager to fetch and update settings at runtime:

   // Get a setting (defaults to null if not found)
   $timeout = $settingManager->get('api_timeout', 30);
   
   // Update a setting
   $settingManager->set('api_timeout', 60);
   

2. Scoped Settings Store environment-specific settings (e.g., dev_* vs. prod_* prefixes) and filter them:

   ekyna_setting:
       scopes:
           dev: ['dev_*']
           prod: ['prod_*']
   

   Retrieve scoped settings:

   $devSettings = $settingManager->getScoped('dev');
   

3. Validation & Defaults Define defaults and validation rules in YAML:

   ekyna_setting:
       settings:
           max_upload_size: { value: 10, type: integer, min: 1, max: 100 }
   

   Access with validation:

   $size = $settingManager->get('max_upload_size'); // Returns 10 (default)
   

4. Frontend Integration Expose settings to JavaScript via a Twig global:

   {{ dump(app.ekyna_setting) }}  {# Renders all settings #}
   

   Or fetch specific settings in a controller and pass to a view:

   return view('dashboard', [
       'settings' => $settingManager->getAll(),
   ]);
   

Integration Tips

• Cache Settings Enable caching in config/packages/ekyna_setting.yaml:

  ekyna_setting:
      cache: true
  

  Clear cache after updates:

  php bin/console cache:clear
  

• Admin Panel Build a CRUD interface for settings using Symfony’s make:crud or a package like EasyAdmin. Example:

  // In a controller
  $settings = $settingManager->getAll();
  return $this->render('admin/settings.html.twig', ['settings' => $settings]);
  

• Environment Overrides Override settings per environment (e.g., .env):

  # config/packages/ekyna_setting.yaml (dev)
  ekyna_setting:
      settings:
          debug_mode: true
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle

   • Last release in 2015; test thoroughly in your Laravel/Symfony version.
   • May require polyfills for modern PHP/Symfony (e.g., Doctrine ORM 2.x+).

2. No Built-in ACL

   • Settings are publicly editable by default. Add middleware or Symfony’s security layer:

     // Example: Protect setting updates
     public function update(SettingManager $manager, Request $request)
     {
         if (!$this->denyAccessUnlessGranted('EDIT_SETTINGS')) {
             throw $this->createAccessDeniedException();
         }
         $manager->set($request->input('key'), $request->input('value'));
     }
     

3. Cache Invalidation

   • Manual cache clearing is required after updates. Consider a custom event listener:

     // src/EventListener/SettingUpdateListener.php
     public function onSettingUpdate(SettingEvent $event)
     {
         $this->container->get('cache')->clear();
     }
     

4. YAML Parsing Quirks

   • Boolean values must be lowercase (true/false), not yes/no.
   • Nested structures (e.g., arrays) may not serialize/deserialize correctly. Flatten them:

     # Bad: May fail
     nested_setting: { key: value }
     # Good:
     nested_setting_key: value
     

Debugging

• Check Database Verify settings are stored in settings table:

  SELECT * FROM settings;
  

• Log Errors Enable debug mode and check logs for Doctrine/ORM issues:

  php bin/console debug:config ekyna_setting
  

Extension Points

1. Custom Storage Override the default Doctrine storage by implementing Ekyna\SettingBundle\Storage\SettingStorageInterface:

   class RedisSettingStorage implements SettingStorageInterface
   {
       public function save(Setting $setting) { /* ... */ }
       public function findByKey($key) { /* ... */ }
   }
   

   Register in services:

   services:
       Ekyna\SettingBundle\Storage\SettingStorageInterface: '@redis_setting_storage'
   

2. Event System Extend with events (e.g., SettingUpdatedEvent) by listening to ekyna_setting.update:

   // config/services.yaml
   Ekyna\SettingBundle\EventListener\SettingEventListener:
       tags:
           - { name: kernel.event_listener, event: ekyna_setting.update, method: onUpdate }
   

3. Twig Extensions Add custom filters/globals for Twig:

   // src/Twig/SettingExtension.php
   class SettingExtension extends \Twig\Extension\AbstractExtension
   {
       public function getFunctions()
       {
           return [
               new \Twig\TwigFunction('get_setting', [$this->manager, 'get']),
           ];
       }
   }
   

   Use in Twig:

   {{ get_setting('app_name') }}