Symfony Config Manipulator Bundle Laravel Package

Getting Started

Minimal Steps for Laravel Adoption

1. Skip Installation: This package is Symfony-specific and cannot be directly used in Laravel. Instead, focus on Laravel’s native config organization.
2. First Use Case: Replace monolithic config/app.php with modular files (e.g., config/auth.php, config/cache.php).
   • Use Laravel’s config:publish for package-specific configs.
   • Manually split config/app.php into smaller files (see Implementation Patterns).
3. Where to Look First:
   • Laravel’s config/ directory structure.
   • php artisan config:publish for package configs.
   • Environment-specific files: config/app.php, config/env.php.

Implementation Patterns

Workflows for Laravel Developers

1. Modularizing Config Files

• Pattern: Split config/app.php into domain-specific files (e.g., config/auth.php, config/queue.php).
• Example:

  // Before: config/app.php (monolithic)
  return [
      'auth' => [...],
      'queue' => [...],
      'cache' => [...],
  ];
  
  // After: config/auth.php, config/queue.php, etc.
  

• Integration:
  • Use config() helper to merge files:

    return array_merge(
        require __DIR__.'/auth.php',
        require __DIR__.'/queue.php',
        // ...
    );
    

  • Or use Laravel’s config caching to auto-merge:

    php artisan config:cache
    

2. Environment-Specific Overrides

• Pattern: Leverage config/env.php for environment-specific settings (e.g., APP_DEBUG, database URLs).
• Example:

  // config/env.php
  return [
      'debug' => env('APP_DEBUG', false),
      'database' => [
          'url' => env('DATABASE_URL'),
      ],
  ];
  

• Integration:
  • Load env.php in config/app.php:

    return array_merge(
        require __DIR__.'/env.php',
        // other configs...
    );
    

3. Package-Specific Configs

• Pattern: Use config:publish to split package configs into config/packages/ (e.g., config/packages/doctrine.php).
• Example:

  php artisan vendor:publish --tag=config
  

• Integration:
  • Merge published configs in config/app.php:

    return array_merge(
        require __DIR__.'/packages/doctrine.php',
        // other configs...
    );
    

4. Custom Artisan Command for Splitting

• Pattern: Create a command to auto-split config/app.php into modular files.
• Example Command:

  // app/Console/Commands/SplitConfig.php
  namespace App\Console\Commands;
  
  use Illuminate\Console\Command;
  use Illuminate\Support\Facades\File;
  
  class SplitConfig extends Command
  {
      protected $signature = 'config:split';
      protected $description = 'Split config/app.php into modular files';
  
      public function handle()
      {
          $configPath = base_path('config/app.php');
          $config = include $configPath;
  
          foreach ($config as $key => $value) {
              if (is_array($value)) {
                  File::put(
                      base_path("config/{$key}.php"),
                      '<?php return ' . var_export($value, true) . ';'
                  );
              }
          }
  
          $this->info('Config files split successfully!');
      }
  }
  

• Usage:

  php artisan config:split
  

5. Merge Conflict Handling

• Pattern: Manually resolve conflicts when splitting or merging configs.
• Example:
  • If config/app.php and config/auth.php both define auth.driver, edit one file to avoid duplication.
  • Use array_merge_recursive() with caution to handle nested conflicts:

    $merged = array_merge_recursive(
        require __DIR__.'/auth.php',
        require __DIR__.'/app.php'
    );
    

Gotchas and Tips

Pitfalls

1. No Direct Laravel Support:

   • This package cannot be used in Laravel. Attempting to install it will cause Composer conflicts (Symfony dependencies vs. Laravel’s constraints).
   • Workaround: Build a custom solution using Laravel’s config system.

2. YAML vs. PHP Arrays:

   • The bundle preserves YAML comments/formatting. Laravel’s PHP configs lose comments when split manually.
   • Tip: Use PHPDoc blocks in PHP configs to document settings:

     /**
      * Authentication settings.
      */
     return [
         'driver' => 'session',
         // ...
     ];
     

3. Config Caching Issues:

   • After splitting config/app.php, run php artisan config:clear and config:cache to avoid stale configs.
   • Gotcha: Forgetting to cache configs after splitting may lead to runtime errors.

4. Merge Conflicts:

   • Splitting configs can introduce duplicate keys (e.g., auth.driver in both config/app.php and config/auth.php).
   • Tip: Use array_replace_recursive() to prioritize specific files:

     $finalConfig = array_replace_recursive(
         require __DIR__.'/base.php',
         require __DIR__.'/auth.php',
         require __DIR__.'/env.php'
     );
     

5. Environment-Specific Files:

   • Laravel’s config/env.php is not auto-loaded by default. Ensure it’s merged in config/app.php.
   • Gotcha: Forgetting to include env.php may cause environment variables to be ignored.

6. Package Config Overrides:

   • Published package configs (e.g., config/packages/doctrine.php) may conflict with manual configs.
   • Tip: Use config:publish with --tag to isolate package configs:

     php artisan config:publish --tag=doctrine --force
     

Debugging Tips

1. Check Config Loading Order:

   • Use php artisan config:clear to reset cached configs.
   • Dump loaded configs to debug:

     dd(config()->all());
     

2. Validate YAML (If Using Hybrid Approach):

   • If you must use YAML (e.g., for legacy reasons), validate with:

     composer require symfony/yaml
     

     use Symfony\Component\Yaml\Yaml;
     
     $yaml = Yaml::parseFile('config/doctrine.yml');
     

3. Handle PHP Syntax Errors:

   • After splitting, ensure all .php config files are valid:

     php -l config/auth.php
     

4. Git Conflict Resolution:

   • Use git diff to track changes when splitting configs:

     git diff config/app.php config/auth.php
     

Extension Points

1. Custom Config Loaders:

   • Extend Laravel’s ConfigRepository to load modular configs:

     // app/Providers/AppServiceProvider.php
     use Illuminate\Support\Facades\Config;
     
     public function boot()
     {
         Config::addPath(base_path('config/modules'));
     }
     

2. Dynamic Config Generation:

   • Use Laravel’s service providers to generate configs dynamically:

     // app/Providers/ConfigGenerator.php
     public function boot()
     {
         $this->mergeConfigFrom(
             __DIR__.'/../config/generated.php',
             'generated'
         );
     }
     

3. Integration with Laravel Forge/Envoyer:

   • Deploy environment-specific configs via Forge/Envoyer:
     • Use config/env.php for runtime overrides.
     • Deploy config/production.php for production-specific settings.

4. Validation Rules:

   • Add validation to config files using Laravel’s validation rules:

     // config/validation.php
     return [
         'auth' => [
             'driver' => 'required|in:session,token',
         ],
     ];
     

   • Validate in a service provider:

     Validator::extend('config_valid', function ($attribute, $value, $parameters) {
         // Custom logic to validate configs
     });