Env Params Builder Bundle Laravel Package

Getting Started

1. Install into a legacy Symfony (2.x/3.x) app:

   composer require piwikpro/env-params-builder-bundle
   

2. Register the bundle in app/AppKernel.php (for Symfony 2/3):

   $bundles = [ /* ... */ new PiwikPro\Bundle\EnvParamsBuilderBundle\EnvParamsBuilderBundle() ];
   

3. Read the README first — specifically the config block that maps environment variable names to parameter keys, and the console command the bundle registers (usually a *:build / *:generate command). The DependencyInjection/Configuration.php is the authoritative reference for the mapping format.
4. Keep your parameters.yml.dist as the template and treat the generated parameters.yml as a build artifact.
5. First use case: in staging/production CI, run the command after checkout and before cache:clear so the container is compiled against the env-var-derived parameters.

Implementation Patterns

• Composer hook integration — wire the generate command into composer.json:

  "scripts": {
    "post-install-cmd": ["@build-params"],
    "post-update-cmd": ["@build-params"],
    "build-params": ["php app/console env-params:build"]
  }
  

  This makes every deploy that runs composer install produce a correct parameters.yml without a manual step.
• Deploy pipeline ordering — the safe sequence is: checkout → composer install --no-dev (triggers builder) → cache:clear --env=prod → cache:warmup --env=prod → run. Skipping warmup leaves you with stale parameters from a previous release.
• Environment parity — define one canonical set of env var names (e.g. SYMFONY__DATABASE_HOST) and reuse them across dev/staging/prod. The bundle reads whatever the process sees, so the mapping config should not branch on environment unless you deliberately override for local dev.
• Local dev fallback — keep a committed parameters.yml for developer machines, and only regenerate in CI. Otherwise a fresh clone without env vars produces a broken file with empty values.
• Secret injection — combine with your platform's secret store (Vault, AWS SSM, Heroku config vars). The bundle does not fetch secrets itself; export them into the process environment first.
• Per-service overrides — for monorepos or multi-app repos, generate a separate parameters.yml per Symfony kernel and pass the output path explicitly if the command supports it.

Gotchas and Tips

• This is pre-%env() technology. Symfony 3.2+ ships natively with %env(FOO)% and env() in parameters.yml, which makes this bundle redundant in modern apps. Use it only to maintain legacy codebases, not for greenfield work.
• Container caching will silently betray you. Newly generated parameters do not take effect until the container is recompiled. Always pair generation with cache:clear. A common bug is "I changed the env var and nothing happened" — that is almost always a warmed cache.
• YAML escaping. Values containing :, #, %, @, or leading/trailing spaces need quoting. If the bundle writes raw string values, values like p@ss:word can corrupt the file. Inspect the generated file and, if needed, wrap sensitive-looking values in single quotes in your source data.
• Silent nulls. Missing env vars typically resolve to null or "" rather than throwing. Add an explicit validation step in your deploy script (or a smoke test that hits a key endpoint) so a missing var fails loudly at deploy time, not at first request.
• Do not commit the generated file. Ship parameters.yml.dist, gitignore parameters.yml, and document the env vars in a .env.example. Committing the generated file is how secrets leak.
• Permissions. The file is written by whichever user runs the command (CI runner, deploy, sometimes www-data). If web and deploy users differ, the generated file can end up unreadable by PHP-FPM. chmod 640 and align group ownership in your deploy script.
• Debugging. Run the generate command with -vvv, then diff the output against parameters.yml.dist. Most failures are a mapping typo (env var name mismatch) or a value type mismatch (string vs. boolean vs. int) — PHP's %parameter% substitution does not coerce types, so "false" stays a truthy string.
• Extension point. If the bundle exposes its builder as a service (check Resources/config/services.yml), you can decorate or replace it to add custom normalization — e.g. casting "true"/"false" to booleans, or JSON-decoding a packed env var. This is cleaner than post-processing the generated YAML.
• Exit criterion for migration. If you're on Symfony 4+, plan to replace this bundle outright with %env()% + Symfony Flex's .env loading. The two approaches conflict if run together, and dual mechanisms make the effective value of a parameter hard to reason about.