Environments in Symfony
We use Symfony a lot at Studio 24 for building modern web applications. Our normal setup is to have a local development environment, a staging environment for clients to test code, and a production live site.
By default Symfony supports the following environments:
- dev – (development) intended for development purposes, can be used locally or on a hosting environment to test your application
- test – (automated tests) intended for use when running automated tests (e.g. phpunit)
- prod – (production) intended for the live web application
Ideally we would have a third web environment to represent staging, which is what we use to preview functionality before go-live. So that’s what I set out to do.
Adding a custom environment
I want to call my new environment stage to represent staging, since Symfony already uses shortened versions for other environments.
It turns out you can just add any old environment name and Symfony recognises this. So setting the new environment locally is really only a matter of updating your local environment settings file .env.local (you can also set this via actual server environment variables).
# Website environment
APP_ENV=stage
Environment configuration
Symfony loads environment variables from .env files. It uses the .env file for default values, then loads the .env.{environment} file for environment-specific settings. Finally, it loads the .env.local file for sensitive variables (e.g. API keys or database credentials – this file should not be committed to version control).
To help keep track of my staging environment variables I created a file at .env.stage to store these.
Package configuration
Different packages use YAML config files in the config/packages folder. I created the folder config/packages/stage/ which is used to store package configuration for the stage environment. It’s possible to inherit values from another environment via the imports key, which is really handy. Here I’m importing the prod settings for the stage environment.
# config/packages/stage/monolog.yaml
imports:
- { resource: '../prod/' }
Composer packages
One gotcha is your PHP code may depend on a library that is loaded by Composer locally in your dev environment (via require-dev), but does not load on stage or prod.
When I first tested the above code, it crashed since Monolog was not found (this is used for logging). It turns out Monolog was loaded in my local dev environment via symfony/debug-pack which is setup to only install on require-dev in my composer file.
This simple composer require command quickly fixed it!
composer require symfony/monolog-bundle
Debug mode
Debug is enabled by default for dev and test environments, and disabled for prod and any new environments.
Normally I’d recommend not displaying debug mode for a staging site, since it is supposed to be an environment to preview the site and should work in the same was as production.
However, you can enable debug and the Symfony debug bar for your new stage environment. First set APP_DEBUG in your .env.local file:
APP_DEBUG=true
Next, ensure the debug bundles are enabled. Edit config/bundles.php and ensure the WebProfilerBundle and DebugBundle are both enabled for the new stage environment.
Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true, 'stage' => true],
Symfony\Bundle\DebugBundle\DebugBundle::class => ['dev' => true, 'test' => true, 'stage' => true]
Finally, create the following config files:
# config/packages/stage/debug.yaml
imports:
- { resource: '../dev/' }
# config/packages/stage/web_profiler.yaml
imports:
- { resource: '../dev/' }
# config/routes/stage/web_profiler.yaml
web_profiler_wdt:
resource: '@WebProfilerBundle/Resources/config/routing/wdt.xml'
prefix: /_wdt
web_profiler_profiler:
resource: '@WebProfilerBundle/Resources/config/routing/profiler.xml'
prefix: /_profiler
Summary
That’s it! It turns out it’s very easy to setup new environments for Symfony 4, most of the work is in enabling any bundles you require and ensuring the right config files are setup for your new environment.