Config Transformer Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require symplify/config-transformer --dev
   

   Register the service provider in config/app.php under providers:

   Symplify\ConfigTransformer\Bootstrap\BootstrapProvider::class,
   

2. First Use Case Convert a Symfony YAML config (e.g., config/packages/doctrine.yaml) to PHP:

   php vendor/bin/config-transformer transform config/packages/doctrine.yaml --format=php
   

   Outputs a PHP array in config/packages/doctrine.php.

3. Where to Look First

   • CLI Command: vendor/bin/config-transformer (for one-off conversions).
   • Service Container: Symplify\ConfigTransformer\ValueObject\ConfigTransformer (for programmatic use).
   • Documentation: Focus on Symplify’s docs for edge cases (e.g., handling nested configs).

Implementation Patterns

Usage Patterns

1. CLI Workflow

   • Use config-transformer in CI/CD pipelines to auto-generate PHP configs from YAML:

     php vendor/bin/config-transformer transform config/packages/*.yaml --format=php --overwrite
     

   • Tip: Combine with git diff to review changes before committing.

2. Programmatic Integration Load and transform configs dynamically in Laravel:

   use Symplify\ConfigTransformer\ValueObject\ConfigTransformer;
   
   $configTransformer = app(ConfigTransformer::class);
   $phpConfig = $configTransformer->transformFileToArray('config/packages/doctrine.yaml');
   

3. Laravel Service Provider Bootstrap configs in register():

   public function register()
   {
       $configs = $this->transformConfigs(['doctrine', 'security']);
       foreach ($configs as $name => $config) {
           $this->mergeConfigFrom($config, "packages/{$name}");
       }
   }
   
   private function transformConfigs(array $names): array
   {
       $transformer = app(ConfigTransformer::class);
       return collect($names)
           ->map(fn($name) => $transformer->transformFileToArray("config/packages/{$name}.yaml"))
           ->toArray();
   }
   

4. Partial Transforms Target specific sections of a YAML file:

   php vendor/bin/config-transformer transform config/packages/security.yaml --format=php --path=firewalls
   

Integration Tips

• Laravel Config Caching: Use the transformed PHP configs with Laravel’s config:cache:

  php artisan config:cache
  

• Environment-Specific Configs: Transform config/packages/dev/doctrine.yaml and config/packages/prod/doctrine.yaml separately, then merge them in config/doctrine.php:

  return array_merge(
      require __DIR__.'/packages/dev/doctrine.php',
      require __DIR__.'/packages/prod/doctrine.php'
  );
  

• Custom Formatters: Extend the transformer for custom output (e.g., JSON for APIs):

  $transformer->transformFileToJson('config/packages/api.yaml');
  

Gotchas and Tips

Pitfalls

1. Parameter References

   • YAML configs often use %parameter% syntax. Ensure parameters are defined in parameters.yaml or passed via --parameters:

     php vendor/bin/config-transformer transform config/packages/security.yaml --parameters=parameters.yaml
     

   • Fix: Use --resolve-parameters to auto-resolve from config/services.yaml or environment variables.

2. Nested Arrays/Objects

   • Complex nested structures (e.g., doctrine.orm.entity_managers) may require explicit path targeting:

     --path=doctrine.orm.entity_managers.default
     

   • Debug: Use --dump-ast to inspect the Abstract Syntax Tree (AST) of the YAML.

3. Overwriting Existing Files

   • --overwrite flag is destructive. Use --dry-run first to preview changes:

     php vendor/bin/config-transformer transform config/packages/*.yaml --format=php --dry-run
     

4. Laravel-Specific Quirks

   • Service Container Tags: YAML tags (e.g., tags: [doctrine.event_subscriber]) are lost in PHP. Manually add them post-transform:

     $config['services']['app.event_subscriber']['tags'] = ['doctrine.event_subscriber'];
     

   • Environment Variables: Replace {% env('APP_DEBUG') %} with Laravel’s env() helper:

     'debug' => (bool) env('APP_DEBUG'),
     

Debugging

• Verbose Output:

  php vendor/bin/config-transformer transform --verbose config/packages/security.yaml
  

• AST Inspection:

  php vendor/bin/config-transformer transform --dump-ast config/packages/security.yaml
  

• Logging: Enable Symfony’s debug mode in config/services.yaml:

  framework:
      debug: true
  

Extension Points

1. Custom Transformers Extend Symplify\ConfigTransformer\ValueObject\Transformer\TransformerInterface to handle domain-specific YAML:

   class CustomTransformer implements TransformerInterface
   {
       public function transform(array $config): array
       {
           // Custom logic (e.g., convert legacy keys)
           return $config;
       }
   }
   

   Register it in BootstrapProvider.

2. Pre/Post-Transform Hooks Use Laravel’s events to modify configs before/after transformation:

   // In a service provider
   event(new ConfigTransforming($yamlPath, $phpConfig));
   

3. Template-Based Transforms Combine with Symfony/Component/Config to validate transformed configs against schemas:

   use Symfony\Component\Config\Loader\LoaderInterface;
   
   $loader = new MyLoader();
   $config = $loader->load($transformedConfig);
   

Tips

• Atomic Commits: Transform one YAML file at a time to isolate changes:

  git add config/packages/doctrine.php && git commit -m "feat: convert doctrine config to PHP"
  

• CI/CD Optimization: Cache transformed configs in .gitignore to speed up builds:

  mkdir -p config/packages/cache && mv config/packages/*.php config/packages/cache/
  

• IDE Support: Use // @phpstan-ignore-next-line for dynamic configs if static analysis complains about type mismatches.
• Backward Compatibility: Keep original YAML files in version control; generate PHP configs via post-install-cmd:

  {
    "scripts": {
      "post-install-cmd": [
        "php vendor/bin/config-transformer transform config/packages/*.yaml --format=php --overwrite"
      ]
    }
  }