Easy Config Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require agence-adeliom/easy-config-bundle
   

   Ensure your config/packages/easy_config.yaml exists (created automatically by Flex).

2. Database Setup: Run migrations:

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

   Or update schema directly:

   php bin/console doctrine:schema:update --force
   

3. First Use Case: Define a configuration entity (e.g., app/config/Config.php):

   namespace App\Config;
   
   use Adeliom\EasyConfigBundle\Entity\Config;
   
   class MyConfig extends Config
   {
       // Custom fields (e.g., public properties or getters/setters)
       public string $mySetting;
   }
   

   Register it in config/packages/easy_config.yaml:

   adeliom_easy_config:
       configs:
           my_config: App\Config\MyConfig
   

4. Accessing Config: Inject the ConfigManager service and fetch your config:

   use Adeliom\EasyConfigBundle\Manager\ConfigManager;
   
   class MyService
   {
       public function __construct(private ConfigManager $configManager) {}
   
       public function getSetting(): string
       {
           return $this->configManager->get('my_config')->mySetting;
       }
   }
   

Implementation Patterns

Core Workflows

1. CRUD via EasyAdmin:

   • The bundle auto-generates an EasyAdmin CRUD interface for all registered configs.
   • Customize the EasyAdmin DSL in config/easyadmin.yaml:

     easy_admin:
         entities:
             App\Config\MyConfig:
                 class: Adeliom\EasyConfigBundle\EasyAdmin\ConfigCrudController
                 label: 'My Config'
     

2. Configuration Hierarchy:

   • Use scopes (e.g., global, tenant) to manage multi-environment configs:

     $configManager->get('my_config', 'tenant_123');
     

   • Define scopes in easy_config.yaml:

     adeliom_easy_config:
         configs:
             my_config:
                 class: App\Config\MyConfig
                 scopes: ['global', 'tenant']
     

3. Validation and Defaults:

   • Add validation constraints to your config class (e.g., Assert\NotBlank).
   • Set defaults via constructor or ConfigManager:

     $config = $configManager->get('my_config', 'default');
     $config->mySetting = $config->mySetting ?? 'default_value';
     $configManager->save($config);
     

4. Event Listeners:

   • Subscribe to config events (e.g., ConfigUpdatedEvent) to react to changes:

     use Adeliom\EasyConfigBundle\Event\ConfigUpdatedEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class MySubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents(): array
         {
             return [
                 ConfigUpdatedEvent::class => 'onConfigUpdated',
             ];
         }
     
         public function onConfigUpdated(ConfigUpdatedEvent $event): void
         {
             // Handle updates (e.g., cache invalidation)
         }
     }
     

Integration Tips

1. Dependency Injection:

   • Prefer constructor injection for ConfigManager over service locator:

     // Good
     public function __construct(private ConfigManager $configManager) {}
     
     // Avoid
     $this->configManager = $container->get(ConfigManager::class);
     

2. Caching:

   • Cache config values in production to reduce DB load:

     # config/packages/easy_config.yaml
     adeliom_easy_config:
         cache: true
         cache_lifetime: 3600 # 1 hour
     

   • Clear cache manually when configs are updated:

     php bin/console cache:clear
     

3. Environment-Specific Configs:

   • Use Symfony’s %env% placeholders in config values:

     class MyConfig extends Config
     {
         public string $apiKey = '%env(API_KEY)%';
     }
     

4. Testing:

   • Mock ConfigManager in tests:

     $mockConfig = $this->createMock(MyConfig::class);
     $mockConfig->method('getMySetting')->willReturn('test_value');
     
     $configManager = $this->createMock(ConfigManager::class);
     $configManager->method('get')->with('my_config')->willReturn($mockConfig);
     

Gotchas and Tips

Common Pitfalls

1. Migration Conflicts:

   • If you modify the Config entity (e.g., add fields), run:

     php bin/console doctrine:migration:diff
     

   • Avoid manual schema edits; use migrations instead.

2. Circular Dependencies:

   • If configs reference each other (e.g., ConfigA uses ConfigB), load them in a specific order:

     $configA = $configManager->get('config_a');
     $configB = $configManager->get('config_b');
     $configA->setDependency($configB); // Safe after both are loaded
     

3. EasyAdmin Overrides:

   • If the auto-generated EasyAdmin CRUD doesn’t meet needs, extend the controller:

     use Adeliom\EasyConfigBundle\EasyAdmin\ConfigCrudController;
     
     class CustomConfigCrudController extends ConfigCrudController
     {
         public static function getEntityFqcn(): string
         {
             return MyConfig::class;
         }
     
         public function configureFields(string $pageName): iterable
         {
             return [
                 // Custom fields here
             ];
         }
     }
     

   • Register it in easyadmin.yaml:

     easy_admin:
         entities:
             App\Config\MyConfig:
                 class: App\EasyAdmin\CustomConfigCrudController
     

4. Scopes and Fallbacks:

   • Scopes default to global if not specified. Ensure fallback logic:

     $tenantConfig = $configManager->get('my_config', 'tenant_123');
     if (!$tenantConfig->isValid()) {
         $tenantConfig = $configManager->get('my_config', 'global');
     }
     

5. Performance with Large Configs:

   • Avoid loading all configs at once. Fetch only what’s needed:

     // Bad: Loads all configs
     $allConfigs = $configManager->getAll();
     
     // Good: Load specific config
     $config = $configManager->get('my_config');
     

Debugging Tips

1. Enable Debug Mode:

   • Temporarily set debug: true in easy_config.yaml to log config operations:

     adeliom_easy_config:
         debug: true
     

2. Check Database:

   • Verify configs exist in adeliom_easy_config_config table:

     SELECT * FROM adeliom_easy_config_config WHERE name = 'my_config';
     

3. Event Dispatching:

   • Ensure event subscribers are registered in services.yaml:

     services:
         App\EventSubscriber\MySubscriber:
             tags: ['kernel.event_subscriber']
     

4. Clear Cache:

   • If configs aren’t updating, clear the cache:

     php bin/console cache:clear
     

Extension Points

1. Custom Config Storage:

   • Override the default Doctrine storage by implementing ConfigStorageInterface:

     use Adeliom\EasyConfigBundle\Storage\ConfigStorageInterface;
     
     class CustomConfigStorage implements ConfigStorageInterface
     {
         public function save(Config $config): void
         {
             // Custom logic (e.g., Redis, API)
         }
     
         public function get(string $name, ?string $scope = null): ?Config
         {
             // Custom logic
         }
     }
     

   • Register it in easy_config.yaml:

     adeliom_easy_config:
         storage: App\Storage\CustomConfigStorage
     

2. Dynamic Configs:

   • Use the ConfigManager to generate configs dynamically:

     $config = new MyConfig();
     $config->name = 'dynamic_' . uniqid();
     $configManager->save($config);
     

3. Serialization:

   • Extend Config to handle complex data (e.g., arrays) via __serialize()/__unserialize():

     class ComplexConfig extends Config
     {
         private array $nestedData = [];
     
         public function __serialize(): array
         {
             return ['nestedData' => $this->nestedData];
         }
     
         public function __unserialize(array $data): void
         {
             $this->nestedData = $data['nestedData'];
         }
     }