Cmsconfiguratorbundle Laravel Package

Getting Started

Minimal Steps

1. Installation Require the package via Composer:

   composer require districtweb/cmsconfiguratorbundle
   

   Register the bundle in config/app.php under the providers array:

   DistrictWeb\CmsConfiguratorBundle\DistrictWebCmsConfiguratorBundle::class,
   

2. First Use Case: Dynamic CMS Configuration Create a configuration entity (e.g., PageLayout) and annotate it with the bundle’s traits:

   namespace App\Entities;
   
   use DistrictWeb\CmsConfiguratorBundle\Entity\ConfigurableTrait;
   use DistrictWeb\CmsConfiguratorBundle\Entity\ConfigurableInterface;
   
   class PageLayout implements ConfigurableInterface
   {
       use ConfigurableTrait;
   
       protected $name;
       protected $template;
       protected $isActive;
   }
   

3. Database Setup Publish and run migrations:

   php artisan vendor:publish --provider="DistrictWeb\CmsConfiguratorBundle\DistrictWebCmsConfiguratorBundle" --tag="migrations"
   php artisan migrate
   

4. Access Configuration in Code Retrieve configurations via the bundle’s service container:

   $pageLayout = $this->container->get('district_web.cms_configurator')->getConfig('page_layout');
   

Implementation Patterns

Core Workflows

1. Configuration Definition Define configurations as PHP classes implementing ConfigurableInterface:

   class FeatureToggle implements ConfigurableInterface
   {
       use ConfigurableTrait;
   
       protected $featureName;
       protected $isEnabled;
       protected $environment;
   }
   

2. Configuration Management Use the bundle’s CLI commands for CRUD operations:

   # Create a new configuration entry
   php artisan district_web:config:create FeatureToggle
   
   # Update an existing configuration
   php artisan district_web:config:update FeatureToggle --feature-name="new_feature" --is-enabled=true
   
   # List all configurations
   php artisan district_web:config:list
   

3. Integration with Laravel Services Bind configurations to Laravel’s service container for dependency injection:

   $this->app->bind('config.feature_toggle', function ($app) {
       return $app->make('district_web.cms_configurator')->getConfig('feature_toggle');
   });
   

4. Dynamic Configuration Loading Load configurations dynamically in routes, controllers, or middleware:

   public function showPage(Request $request)
   {
       $layout = $this->container->get('district_web.cms_configurator')->getConfig('page_layout');
       return view('pages.index', ['layout' => $layout]);
   }
   

Advanced Patterns

1. Configuration Validation Implement custom validation logic in the validate() method of your configuration class:

   public function validate()
   {
       if ($this->isActive && empty($this->template)) {
           throw new \InvalidArgumentException("Active layouts must have a template.");
       }
   }
   

2. Configuration Events Subscribe to configuration change events for real-time updates:

   $this->events->listen('district_web.config.updated', function ($config) {
       // Trigger cache invalidation or other side effects
       Cache::forget('config.' . $config->getName());
   });
   

3. Multi-Tenant Configurations Scope configurations by tenant using middleware or service providers:

   public function boot()
   {
       $this->app->resolving('district_web.cms_configurator', function ($configurator, $app) {
           $tenant = $app['tenant'];
           $configurator->setTenant($tenant);
       });
   }
   

Gotchas and Tips

Common Pitfalls

1. Namespace Conflicts The bundle uses Symfony’s dependency injection, which may conflict with Laravel’s container. Ensure proper binding:

   $this->app->bind('district_web.cms_configurator', function ($app) {
       return new \DistrictWeb\CmsConfiguratorBundle\Service\Configurator(
           $app['config'],
           $app['db']
       );
   });
   

2. Migration Issues The bundle’s migrations assume a specific database schema. Customize them by publishing and modifying:

   php artisan vendor:publish --provider="DistrictWeb\CmsConfiguratorBundle\DistrictWebCmsConfiguratorBundle" --tag="migrations"
   

3. Caching Quirks Configurations loaded via the bundle are not automatically cached by Laravel. Implement manual caching:

   $config = Cache::remember("config.{$configName}", 60, function () use ($configName) {
       return $this->container->get('district_web.cms_configurator')->getConfig($configName);
   });
   

4. Symfony Dependency Overhead The bundle pulls in Symfony components (e.g., Yaml, Config). If this causes bloat, consider forking and replacing Symfony-specific logic with Laravel equivalents.

Debugging Tips

1. Enable Debug Mode Set APP_DEBUG=true in .env to get detailed error messages for configuration loading issues.

2. Log Configuration Changes Add logging to track configuration updates:

   $this->events->listen('district_web.config.updated', function ($config) {
       \Log::info("Configuration updated: {$config->getName()}", ['data' => $config->toArray()]);
   });
   

3. Check for Deprecated Methods The bundle may use Symfony’s deprecated APIs. Update them in a fork if needed:

   // Example: Replace deprecated YamlFileLoader
   $loader = new \Symfony\Component\Config\Loader\LoaderResolver();
   

Extension Points

1. Custom Configuration Storage Override the default storage backend by implementing ConfigStorageInterface:

   class CustomConfigStorage implements ConfigStorageInterface
   {
       public function save(ConfigurableInterface $config)
       {
           // Custom logic (e.g., Redis, S3)
       }
   
       public function find($name)
       {
           // Custom logic
       }
   }
   

2. Add Configuration Types Extend the bundle’s configuration system by creating new traits or interfaces:

   trait MultiTenantConfigurableTrait
   {
       public function setTenant($tenant)
       {
           $this->tenant = $tenant;
       }
   }
   

3. Integrate with Laravel’s Config System Sync bundle configurations with Laravel’s config/ directory:

   $this->app->booting(function () {
       $configurator = $this->app->make('district_web.cms_configurator');
       $configs = $configurator->getAllConfigs();
       foreach ($configs as $config) {
           config([$config->getName() => $config->toArray()]);
       }
   });
   

Performance Considerations

1. Avoid Over-Fetching Load only the configurations you need:

   $configurator->getConfig('specific_config_name'); // Instead of getAllConfigs()
   

2. Batch Database Operations For bulk updates, use transactions:

   DB::transaction(function () use ($configurator, $configs) {
       foreach ($configs as $config) {
           $configurator->updateConfig($config);
       }
   });
   

3. Lazy-Load Configurations Defer loading configurations until they’re needed:

   $configurator->lazyLoad('expensive_config');