Laminas Config Aggregator Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laminas/laminas-config-aggregator
   

   For multi-format support (JSON, YAML, INI, XML):

   composer require laminas/laminas-config
   

2. Basic Usage: Create a ConfigAggregator instance with providers (e.g., PHP files):

   use Laminas\ConfigAggregator\ConfigAggregator;
   use Laminas\ConfigAggregator\PhpFileProvider;
   
   $aggregator = new ConfigAggregator([
       new PhpFileProvider('config/*.global.php'),
   ]);
   $config = $aggregator->getMergedConfig();
   

3. First Use Case:

   • Organize config files (e.g., db.global.php, cache.global.php) in a directory.
   • Merge them into a single array with precedence based on file order.

Implementation Patterns

Core Workflows

1. Provider-Based Configuration:

   • Use PhpFileProvider for PHP arrays or LaminasConfigProvider for JSON/YAML/INI/XML.
   • Example:

     $aggregator = new ConfigAggregator([
         new LaminasConfigProvider('config/*.{json,yaml}'),
         new PhpFileProvider('config/*.php'),
     ]);
     

2. Dynamic Providers:

   • Implement __invoke() in custom classes for reusable config logic:

     class AppConfig {
         public function __invoke() {
             return ['app' => ['name' => 'MyApp']];
         }
     }
     $aggregator = new ConfigAggregator([AppConfig::class]);
     

3. Environment-Specific Configs:

   • Use glob patterns to load environment-specific files:

     new PhpFileProvider('config/{production,staging,development}.php')
     

4. Caching for Performance:

   • Cache merged configs in production (e.g., using Laminas\Cache):

     $cache = new FilesystemCache('path/to/cache');
     $aggregator = new ConfigAggregator([...], $cache);
     

Integration Tips

• Laravel-Specific:

  • Bind the aggregator to the container in AppServiceProvider:

    $this->app->singleton(ConfigAggregator::class, function ($app) {
        return new ConfigAggregator([
            new PhpFileProvider(config_path('*.php')),
        ], $app->make(Cache::class));
    });
    

  • Access configs via app(ConfigAggregator::class)->getMergedConfig().

• Modular Configs:

  • Use pre-processors to dynamically add providers based on installed packages:

    $aggregator = new ConfigAggregator([], null, [], [
        function (iterable $providers) {
            if (class_exists('Vendor\Package\Config')) {
                $providers[] = new Vendor\Package\Config();
            }
            return $providers;
        }
    ]);
    

Gotchas and Tips

Pitfalls

1. Duplicate Providers:

   • Throw InvalidConfigProviderException if the same class or instance is added twice.
   • Fix: Use unique instances or check for duplicates manually.

2. Globbing Quirks:

   • PhpFileProvider uses Laminas\Stdlib\Glob if available (cross-platform patterns like *.{json,yaml}).
   • Tip: Install laminas/laminas-stdlib for advanced globbing.

3. Precedence Overrides:

   • Later providers override earlier ones. Explicitly order providers to avoid surprises:

     // Overrides 'db' from earlier providers
     new PhpFileProvider('config/database.php')
     

4. Caching Caveats:

   • Cached configs may not reflect file changes. Use cache()->forget() or disable caching in development.

Debugging

• Verify Merged Config:

  var_dump($aggregator->getMergedConfig());
  

• Isolate Providers: Test each provider in isolation to identify misconfigurations:

  $provider = new PhpFileProvider('config/*.php');
  foreach ($provider as $config) {
      var_dump($config);
  }
  

Extension Points

1. Custom Providers:

   • Implement __invoke() for reusable logic (e.g., database-driven configs):

     class DatabaseConfig {
         public function __invoke() {
             return DB::table('config')->get()->toArray();
         }
     }
     

2. Post-Processors:

   • Transform configs after merging (e.g., validate or normalize):

     $aggregator = new ConfigAggregator([...], null, [
         function (array $config) {
             return array_map('strtolower', $config);
         }
     ]);
     

3. Environment Variables:

   • Use post-processors to replace placeholders with .env values:

     $aggregator = new ConfigAggregator([...], null, [
         function (array $config) {
             return preg_replace_callback('/%(.+)%/', function ($matches) {
                 return env($matches[1], $matches[0]);
             }, $config);
         }
     ]);
     

Performance Tips

• Lazy Loading: Use generators for large config sets to avoid memory spikes:

  new PhpFileProvider('config/*.php') // Already a generator
  

• Cache Invalidation: Implement a cache key versioning system to force refreshes:

  $cacheKey = 'config_v2_' . filemtime('config/database.php');
  $cache->save($cacheKey, $config);