Setting Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bluetea/setting-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       BlueTea\SettingBundle\BlueTeaSettingBundle::class => ['all' => true],
   ];
   

2. Database Setup: Run migrations (check src/Resources/doc/installation.md for schema). Example:

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

3. First Use Case: Define a setting via YAML (e.g., config/settings.yml):

   app:
       site_name: "My App"
       maintenance_mode: false
   

   Load and use in a controller:

   use BlueTea\SettingBundle\Manager\AppSettingManager;
   
   class DefaultController extends AbstractController {
       public function index(AppSettingManager $settingManager) {
           $siteName = $settingManager->get('app.site_name');
           return $this->render('index.html.twig', ['siteName' => $siteName]);
       }
   }
   

Implementation Patterns

Core Workflows

1. App Settings (Key-Value Store):

   • CRUD via CLI:

     # Set a value
     php bin/console bluetea:setting:set app.site_name "New Name"
     
     # Get a value (in code)
     $value = $settingManager->get('app.site_name', 'default');
     
     # List all settings
     $allSettings = $settingManager->all();
     

   • Scoped Settings (per user/system):

     // System-wide
     $settingManager->set('app.theme', 'dark', 'system');
     
     // User-specific (requires user context)
     $settingManager->set('user.theme', 'light', 'user', $userId);
     

2. Entity Settings:

   • Define a setting for an entity (e.g., Product):

     // In Product entity
     use BlueTea\SettingBundle\Model\EntitySettingInterface;
     
     class Product implements EntitySettingInterface {
         // ...
     }
     

   • Access via EntitySettingManager:

     $productSetting = $entitySettingManager->getSetting($product, 'price_discount');
     $entitySettingManager->setSetting($product, 'price_discount', 10);
     

3. Validation:

   • Use Symfony’s validator with constraints:

     # config/validator/validation.yml
     BlueTea\SettingBundle\Model\AppSetting:
         properties:
             value:
                 - Type: string
                 - NotBlank: ~
     

4. Caching:

   • Enable caching in config/packages/bluetea_setting.yaml:

     bluetea_setting:
         app:
             cache: true
             cache_lifetime: 3600
     

Integration Tips

• Twig Integration: Extend Twig with a custom extension to access settings globally:

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

  Usage in Twig:

  {{ setting('app.site_name') }}
  

• Event Listeners: Subscribe to setting changes for side effects:

  // src/EventListener/SettingListener.php
  class SettingListener {
      public function onSettingUpdate(SettingEvent $event) {
          if ($event->getSetting()->getKey() === 'app.maintenance_mode') {
              // Trigger maintenance mode logic
          }
      }
  }
  

  Register in services.yaml:

  services:
      App\EventListener\SettingListener:
          tags:
              - { name: kernel.event_listener, event: bluetea.setting.update, method: onSettingUpdate }
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • Last release in 2014—assume no active maintenance. Test thoroughly in staging.
   • Check for Doctrine ORM version compatibility (likely tied to Symfony 2.x).

2. User-Scoped Settings:

   • User-scoped settings require explicit $userId in set()/get(). Omitting it defaults to system scope.
   • Example of silent failure:

     // Fails silently if $userId is missing
     $settingManager->get('user.theme', null, 'user');
     

3. Database Schema:

   • The bundle expects tables app_setting and entity_setting. Manual schema changes may break migrations.
   • If using custom tables, override the entity mappings in config/packages/bluetea_setting.yaml:

     bluetea_setting:
         app:
             entity: App\Entity\CustomAppSetting
         entity:
             entity: App\Entity\CustomEntitySetting
     

4. Caching Quirks:

   • Cache invalidation is manual. Clear cache after bulk updates:

     php bin/console cache:clear
     

   • Cache lifetime is global for all app settings. Adjust via config.

5. Entity Settings:

   • Requires entities to implement EntitySettingInterface. Forgetting this causes runtime errors.
   • No built-in support for soft-deletes or versioning in entity settings.

Debugging Tips

1. Check for Missing Config:

   • If settings return null, verify config/packages/bluetea_setting.yaml exists and is loaded.

2. Doctrine Events:

   • Enable SQL logging to debug queries:

     # config/packages/dev/doctrine.yaml
     doctrine:
         dbal:
             logging: true
             profiling: true
     

3. CLI Command Issues:

   • Commands like bluetea:setting:set may fail if the AppSetting entity is misconfigured. Rebuild the cache:

     php bin/console cache:clear --env=dev
     

Extension Points

1. Custom Setting Types:

   • Extend the AppSetting entity to add metadata (e.g., description, group):

     // src/Entity/AppSetting.php
     class AppSetting extends AbstractAppSetting {
         private $description;
         private $group;
         // Add getters/setters and update migrations.
     }
     

2. Custom Validation:

   • Override the validator for specific keys:

     # config/validator/validation.yml
     BlueTea\SettingBundle\Model\AppSetting:
         constraints:
             - Callback: { callback: ['App\Validator\SettingValidator', 'validate'] }
     

3. Event Dispatching:

   • Extend the bundle’s event system to log changes or trigger notifications:

     // src/EventSubscriber/SettingSubscriber.php
     class SettingSubscriber implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 SettingEvents::PRE_SET => 'onPreSet',
                 SettingEvents::POST_SET => 'onPostSet',
             ];
         }
     }
     

4. Alternative Storage:

   • Replace the Doctrine-based storage with Redis or a flat file by implementing SettingStorageInterface:

     class RedisSettingStorage implements SettingStorageInterface {
         public function save(AppSetting $setting) { /* ... */ }
         public function find($key, $scope = null) { /* ... */ }
     }
     

   • Bind it in services.yaml:

     services:
         Bluetea\SettingBundle\Manager\AppSettingManager:
             arguments:
                 $storage: '@redis_setting_storage'
     

5. Bulk Operations:

   • For large-scale updates, use Doctrine’s EntityManager directly:

     $settings = $entityManager->getRepository(AppSetting::class)->findBy(['scope' => 'system']);
     foreach ($settings as $setting) {
         $setting->setValue($newValue);
     }
     $entityManager->flush();