Composer Parameter Handler Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package solves a configuration management problem in Laravel/PHP applications by automating the generation of .env-like parameter files (e.g., parameters.yml) from a .dist template during composer install/update. This aligns well with Laravel’s 12-factor app principles (config separation, environment parity) and Symfony’s parameter handling patterns.
• Laravel-Specific Synergy:
  • Laravel’s .env files and Symfony’s parameters.yml serve similar purposes (environment-specific configs). While Laravel primarily uses .env, this package could complement legacy Symfony bundles or hybrid Laravel/Symfony apps (e.g., Lumen, Laravel with Symfony components).
  • For pure Laravel, the package is indirectly useful if:
    • The team uses YAML-based configs (e.g., config/parameters.yml) alongside .env.
    • The app integrates with Symfony components requiring parameters.yml.
    • The team prefers YAML over .env for structured configs (e.g., database clusters, feature flags).
• Alternatives: Laravel’s native .env + env() helper or config() caching already handles most use cases. This package adds value only for non-.env workflows or multi-framework projects.

Integration Feasibility

• Low Friction: Requires minimal changes—just:
  1. Add the package to composer.json.
  2. Configure extra.incenteev-parameters to point to the .dist and target files.
  3. Hook into post-install-cmd/post-update-cmd.
• Compatibility:
  • Laravel: Works if the app uses parameters.yml (not .env). Conflicts unlikely unless mixing config sources.
  • Symfony: Native fit; ideal for Laravel apps using Symfony’s DependencyInjection.
  • PHP 8.0+: Required (package supports PHP 8.0+; Laravel 9+ is PHP 8.1+).
• Template Format: Expects a .dist file with a top-level parameters key (e.g., parameters.yml.dist). Laravel’s .env files won’t work without adaptation.

Technical Risk

• Risk 1: Configuration Drift
  • Issue: If parameters.yml.dist is manually edited post-install, the package will overwrite changes during composer update.
  • Mitigation: Document this behavior clearly and enforce a git-ignored workflow for the .dist file.
• Risk 2: Laravel-Specific Gaps
  • Issue: Laravel’s config() cache may ignore parameters.yml if not loaded via a service provider.
  • Mitigation: Ensure the YAML file is merged into Laravel’s config (e.g., via ConfigServiceProvider).
• Risk 3: Overhead for Simple Apps
  • Issue: Adds complexity for teams already using .env effectively.
  • Mitigation: Justify only for multi-environment configs or Symfony interop.

Key Questions for Adoption

1. Why YAML? Does the team need structured configs (e.g., nested arrays) that .env can’t handle?
2. Symfony Integration? Is the app using Symfony components requiring parameters.yml?
3. CI/CD Impact: Will composer install in CI/CD environments re-generate configs, causing flakiness?
4. Backup Strategy: How will teams protect parameters.yml from accidental overwrites?
5. Laravel-Specific Workflow: How will parameters.yml values be exposed to Laravel’s config() system?

Integration Approach

Stack Fit

• Primary Use Case:
  • Laravel + Symfony: Ideal for apps using Symfony’s ParameterBag or ContainerInterface.
  • Legacy Apps: Useful if migrating from Symfony to Laravel while retaining YAML configs.
• Secondary Use Case:
  • Non-.env Configs: Teams preferring YAML for complex, hierarchical configs (e.g., database replicas, feature toggles).
• Anti-Pattern: Avoid for pure Laravel apps relying solely on .env unless there’s a specific need for YAML.

Migration Path

1. Assessment Phase:
   • Audit existing configs: Identify if .env can be replaced or supplemented with YAML.
   • Check for Symfony dependencies requiring parameters.yml.
2. Pilot Phase:
   • Start with non-critical configs (e.g., app/config/parameters.yml for logging).
   • Test composer install/update to verify file generation.
3. Full Adoption:
   • Replace .env variables with YAML where beneficial (e.g., parameters.yml for database clusters).
   • Update Laravel’s ConfigServiceProvider to merge YAML configs:

     $this->mergeConfigFrom(__DIR__.'/../../config/parameters.yml', 'parameters');
     

4. Deprecation:
   • Phase out .env usage for YAML-covered configs (document migration steps).

Compatibility

Sequencing

1. Add Dependency:

   composer require incenteev/composer-parameter-handler
   

2. Configure composer.json:

   "extra": {
     "incenteev-parameters": {
       "file": "config/parameters.yml"
     }
   },
   "scripts": {
     "post-install-cmd": ["Incenteev\\ParameterHandler\\ScriptHandler::buildParameters"],
     "post-update-cmd": ["Incenteev\\ParameterHandler\\ScriptHandler::buildParameters"]
   }
   

3. Create Template:
   • Rename parameters.yml.dist to parameters.yml (or vice versa) with placeholders:

     parameters:
       database.host: "%env(DATABASE_HOST)%"  # Example: Bridge YAML and .env
       cache.redis.host: "127.0.0.1"
     

4. Integrate with Laravel:
   • Load YAML in a service provider:

     $parameters = Yaml::parse(file_get_contents(__DIR__.'/../../config/parameters.yml'));
     $this->mergeConfigFrom($parameters, 'parameters');
     

5. Test:
   • Verify composer install generates parameters.yml.
   • Check Laravel’s config('parameters.database.host') works.

Operational Impact

Maintenance

• Pros:
  • Centralized Configs: Single source of truth for environment-specific values (.dist file).
  • Version Control: .dist file can be committed to Git (unlike .env).
  • Auditability: Changes to configs are tracked via Git.
• Cons:
  • Overwrite Risk: composer update will clobber parameters.yml if edited.
  • Additional Files: Requires maintaining .dist templates.
• Mitigation:
  • Document that parameters.yml should be git-ignored (or use a parameters.yml.example).
  • Use Composer’s post-autoload-dump instead of post-install-cmd to avoid CI/CD regen.

Support

• Debugging:
  • Issue: Missing configs or incorrect values.
  • Debug Steps:
    1. Verify parameters.yml.dist exists and is valid YAML.
    2. Check composer.json scripts are correctly hooked.
    3. Ensure Laravel’s service provider merges the YAML.
• Common Pitfalls:
  • Forgetting to commit .dist files.
  • Mixing .env and YAML without a bridge (e.g., using %env() placeholders in YAML).
• Support Tools:
  • Add a health check in Laravel’s AppServiceProvider to validate parameters.yml exists.

Scaling

• Performance:
  • Negligible Impact: File generation is a one-time composer operation; no runtime overhead.
• Multi-Environment:
  • Pro: Easier to manage environment-specific configs via .dist templates (e.g., parameters.yml.dist.staging).
  • Con: Requires environment-specific .dist files or a build step to swap them.
• Microservices:
  • Useful: Each service can have its own parameters.yml generated independently.

Failure Modes