Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Cookbook
  4. Configuration
  5. How to Master and Create new Environments
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Different Environments, Different Configuration Files
  • Executing an Application in Different Environments
  • Creating a New Environment
  • Environments and the Cache Directory
  • Going Further

How to Master and Create new Environments

Edit this page

Warning: You are browsing the documentation for Symfony 2.2, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

How to Master and Create new Environments

Every application is the combination of code and a set of configuration that dictates how that code should function. The configuration may define the database being used, whether or not something should be cached, or how verbose logging should be. In Symfony2, the idea of "environments" is the idea that the same codebase can be run using multiple different configurations. For example, the dev environment should use configuration that makes development easy and friendly, while the prod environment should use a set of configuration optimized for speed.

Different Environments, Different Configuration Files

A typical Symfony2 application begins with three environments: dev, prod, and test. As discussed, each "environment" simply represents a way to execute the same codebase with different configuration. It should be no surprise then that each environment loads its own individual configuration file. If you're using the YAML configuration format, the following files are used:

  • for the dev environment: app/config/config_dev.yml
  • for the prod environment: app/config/config_prod.yml
  • for the test environment: app/config/config_test.yml

This works via a simple standard that's used by default inside the AppKernel class:

1
2
3
4
5
6
7
8
9
10
11
12
13
// app/AppKernel.php

// ...

class AppKernel extends Kernel
{
    // ...

    public function registerContainerConfiguration(LoaderInterface $loader)
    {
        $loader->load(__DIR__.'/config/config_'.$this->getEnvironment().'.yml');
    }
}

As you can see, when Symfony2 is loaded, it uses the given environment to determine which configuration file to load. This accomplishes the goal of multiple environments in an elegant, powerful and transparent way.

Of course, in reality, each environment differs only somewhat from others. Generally, all environments will share a large base of common configuration. Opening the "dev" configuration file, you can see how this is accomplished easily and transparently:

  • YAML
  • XML
  • PHP
1
2
3
imports:
    - { resource: config.yml }
# ...
1
2
3
4
<imports>
    <import resource="config.xml" />
</imports>
<!-- ... -->
1
2
$loader->import('config.php');
// ...

To share common configuration, each environment's configuration file simply first imports from a central configuration file (config.yml). The remainder of the file can then deviate from the default configuration by overriding individual parameters. For example, by default, the web_profiler toolbar is disabled. However, in the dev environment, the toolbar is activated by modifying the default value in the dev configuration file:

  • YAML
  • XML
  • PHP
1
2
3
4
5
6
7
# app/config/config_dev.yml
imports:
    - { resource: config.yml }

web_profiler:
    toolbar: true
    # ...
1
2
3
4
5
6
7
8
<!-- app/config/config_dev.xml -->
<imports>
    <import resource="config.xml" />
</imports>

<webprofiler:config
    toolbar="true"
    ... />
1
2
3
4
5
6
7
8
// app/config/config_dev.php
$loader->import('config.php');

$container->loadFromExtension('web_profiler', array(
    'toolbar' => true,

    // ...
));

Executing an Application in Different Environments

To execute the application in each environment, load up the application using either the app.php (for the prod environment) or the app_dev.php (for the dev environment) front controller:

1
2
http://localhost/app.php      -> *prod* environment
http://localhost/app_dev.php  -> *dev* environment

Note

The given URLs assume that your web server is configured to use the web/ directory of the application as its root. Read more in Installing Symfony2.

If you open up one of these files, you'll quickly see that the environment used by each is explicitly set:

1
2
3
4
5
6
// web/app.php
// ... 

$kernel = new AppKernel('prod', false);

// ...

As you can see, the prod key specifies that this environment will run in the prod environment. A Symfony2 application can be executed in any environment by using this code and changing the environment string.

Note

The test environment is used when writing functional tests and is not accessible in the browser directly via a front controller. In other words, unlike the other environments, there is no app_test.php front controller file.

Debug Mode

Important, but unrelated to the topic of environments is the false argument as the second argument to the AppKernel constructor. This specifies whether or not the application should run in "debug mode". Regardless of the environment, a Symfony2 application can be run with debug mode set to true or false. This affects many things in the application, such as whether or not errors should be displayed or if cache files are dynamically rebuilt on each request. Though not a requirement, debug mode is generally set to true for the dev and test environments and false for the prod environment.

Internally, the value of the debug mode becomes the kernel.debug parameter used inside the service container. If you look inside the application configuration file, you'll see the parameter used, for example, to turn logging on or off when using the Doctrine DBAL:

  • YAML
  • XML
  • PHP
1
2
3
4
doctrine:
   dbal:
       logging:  "%kernel.debug%"
       # ...
1
<doctrine:dbal logging="%kernel.debug%" ... />
1
2
3
4
5
6
7
8
$container->loadFromExtension('doctrine', array(
    'dbal' => array(
        'logging'  => '%kernel.debug%',

        // ...
    ),
    // ...
));

Creating a New Environment

By default, a Symfony2 application has three environments that handle most cases. Of course, since an environment is nothing more than a string that corresponds to a set of configuration, creating a new environment is quite easy.

Suppose, for example, that before deployment, you need to benchmark your application. One way to benchmark the application is to use near-production settings, but with Symfony2's web_profiler enabled. This allows Symfony2 to record information about your application while benchmarking.

The best way to accomplish this is via a new environment called, for example, benchmark. Start by creating a new configuration file:

  • YAML
  • XML
  • PHP
1
2
3
4
5
6
# app/config/config_benchmark.yml
imports:
    - { resource: config_prod.yml }

framework:
    profiler: { only_exceptions: false }
1
2
3
4
5
6
7
8
<!-- app/config/config_benchmark.xml -->
<imports>
    <import resource="config_prod.xml" />
</imports>

<framework:config>
    <framework:profiler only-exceptions="false" />
</framework:config>
1
2
3
4
5
6
// app/config/config_benchmark.php
$loader->import('config_prod.php')

$container->loadFromExtension('framework', array(
    'profiler' => array('only-exceptions' => false),
));

And with this simple addition, the application now supports a new environment called benchmark.

This new configuration file imports the configuration from the prod environment and modifies it. This guarantees that the new environment is identical to the prod environment, except for any changes explicitly made here.

Because you'll want this environment to be accessible via a browser, you should also create a front controller for it. Copy the web/app.php file to web/app_benchmark.php and edit the environment to be benchmark:

1
2
3
4
5
6
7
// web/app_benchmark.php


// change just this line
$kernel = new AppKernel('benchmark', false);

// ...

The new environment is now accessible via:

1
http://localhost/app_benchmark.php

Note

Some environments, like the dev environment, are never meant to be accessed on any deployed server by the general public. This is because certain environments, for debugging purposes, may give too much information about the application or underlying infrastructure. To be sure these environments aren't accessible, the front controller is usually protected from external IP addresses via the following code at the top of the controller:

1
2
3
if (!in_array(@$_SERVER['REMOTE_ADDR'], array('127.0.0.1', '::1'))) {
    die('You are not allowed to access this file. Check '.basename(__FILE__).' for more information.');
}

Environments and the Cache Directory

Symfony2 takes advantage of caching in many ways: the application configuration, routing configuration, Twig templates and more are cached to PHP objects stored in files on the filesystem.

By default, these cached files are largely stored in the app/cache directory. However, each environment caches its own set of files:

1
2
app/cache/dev   - cache directory for the *dev* environment
app/cache/prod  - cache directory for the *prod* environment

Sometimes, when debugging, it may be helpful to inspect a cached file to understand how something is working. When doing so, remember to look in the directory of the environment you're using (most commonly dev while developing and debugging). While it can vary, the app/cache/dev directory includes the following:

  • appDevDebugProjectContainer.php - the cached "service container" that represents the cached application configuration;
  • appDevUrlGenerator.php - the PHP class generated from the routing configuration and used when generating URLs;
  • appDevUrlMatcher.php - the PHP class used for route matching - look here to see the compiled regular expression logic used to match incoming URLs to different routes;
  • twig/ - this directory contains all the cached Twig templates.

Note

You can easily change the directory location and name. For more information read the article How to override Symfony's Default Directory Structure.

Going Further

Read the article on How to Set External Parameters in the Service Container.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    No stress: we've got you covered with our 116 automated quality checks of your code

    No stress: we've got you covered with our 116 automated quality checks of your code

    Code consumes server resources. Blackfire tells you how

    Code consumes server resources. Blackfire tells you how

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Kamil Breguła, a Symfony contributor

    Thanks Kamil Breguła for being a Symfony contributor

    1 commit • 2 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia