Config File Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require arthem/config-file-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Arthem\ConfigFileBundle\ArthemConfigFileBundle::class => ['all' => true],
   ];
   

2. First Use Case: Define a file in config/packages/arthem_config_file.yaml:

   arthem_config_file:
       files:
           jwt_key:
               extension: pem
               content: '%env(JWT_PRIVATE_KEY)%'
   

   Reference it in your service configuration:

   # config/packages/security.yaml
   jwt_provider:
       private_key_file: '%arthem_config_file.file.jwt_key%'
   

3. Verify: Clear cache (php bin/console cache:clear) and check the generated file in var/cache/{env}/arthem_config_file/.

Implementation Patterns

Workflows

1. Docker/Env-First Deployments:

   • Store sensitive files (e.g., JWT keys, service account JSON) as environment variables.
   • Use arthem_config_file to dynamically generate files from these vars during runtime.
   • Example: Replace private_key_file: /path/to/key.pem with %arthem_config_file.file.jwt_key%.

2. Template-Based Configs:

   • Use inline YAML syntax for simple files:

     some_service:
         config_file: |
             &file:config.json
             %env(json_string:CONFIG_DATA)%
     

   • Ideal for multi-line or structured configs (e.g., JSON, PEM).

3. Multi-Environment Setups:

   • Override arthem_config_file per environment (e.g., config/packages/dev/arthem_config_file.yaml).
   • Use %kernel.environment% in file paths if needed (though the bundle handles hashing).

Integration Tips

• Symfony Parameters: Reference generated files in config/packages/parameters.yaml:

  parameters:
      app.jwt_key_path: '%arthem_config_file.file.jwt_key%'
  

• Dependency Injection: Inject the file path directly into services:

  // src/Service/JwtService.php
  public function __construct(string $privateKeyPath) {
      $this->privateKeyPath = $privateKeyPath;
  }
  

  # config/services.yaml
  services:
      App\Service\JwtService:
          arguments:
              $privateKeyPath: '%arthem_config_file.file.jwt_key%'
  

• Validation: Use Symfony’s validator to ensure files exist post-generation (e.g., in a compiler pass).

Gotchas and Tips

Pitfalls

1. Cache Dependency:

   • Generated files are not hot-reloaded. Clear cache (php bin/console cache:clear) after changing env vars or configs.
   • Debugging Tip: Check var/cache/{env}/arthem_config_file/ for generated files. Use php bin/console debug:config arthem_config_file to verify config.

2. Environment Variable Resolution:

   • Ensure env vars are loaded before Symfony’s config phase (e.g., via .env.local or Docker environment:).
   • Error: ParameterNotFoundException for %env(FOO)% → Verify .env files are loaded or use php bin/console debug:container --parameters to check resolved vars.

3. File Naming Collisions:

   • The bundle appends a hash to filenames (e.g., jwt_key-c131d7b5.pem). Avoid hardcoding paths in configs.
   • Workaround: Use %arthem_config_file.file.jwt_key% (resolved path) instead of raw paths.

4. Multiline Env Vars:

   • Use json_string processor for JSON configs to avoid escaping issues:

     content: '%env(json_string:MULTILINE_JSON)%'
     

Debugging

• Log Generated Files: Add a compiler pass to log file paths:

  use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
  use Symfony\Component\DependencyInjection\ContainerBuilder;
  
  class LogConfigFilesPass implements CompilerPassInterface {
      public function process(ContainerBuilder $container) {
          $files = $container->getParameter('arthem_config_file.files');
          foreach ($files as $name => $file) {
              $container->getDefinition('logger')->addMethodCall(
                  'info',
                  ['Generated file: ' . $file['path']]
              );
          }
      }
  }
  

  Register it in config/services.yaml:

  services:
      App\DependencyInjection\LogConfigFilesPass:
          tags: [compiler]
  

Extension Points

1. Custom File Paths: Override the cache directory in config/packages/arthem_config_file.yaml:

   arthem_config_file:
       cache_dir: '%kernel.project_dir%/var/custom_config_files'
   

2. Pre/Post-Processing: Extend the bundle’s FileGenerator service to modify content before writing:

   // src/DependencyInjection/ConfigFileExtension.php
   public function load(array $configs, ContainerConfigurator $container) {
       $container->services()
           ->set('arthem_config_file.file_generator')
           ->call('setCustomProcessor', [fn($content) => str_replace('OLD', 'NEW', $content)]);
   }
   

3. Dynamic File Generation: Use a compiler pass to generate files conditionally:

   class DynamicConfigPass implements CompilerPassInterface {
       public function process(ContainerBuilder $container) {
           if ($container->hasParameter('app.generate_dynamic_files')) {
               $container->getExtension('arthem_config_file')->addFile(
                   'dynamic_file',
                   ['extension' => 'json', 'content' => '%env(DYNAMIC_CONTENT)%']
               );
           }
       }
   }