Development Documentation Deployment Multi Environment

Warning: You are browsing the documentation from version 4 to 10 of Pimcore. Please visit https://pimcore.com/docs/platform/ for the latest versions of Pimcore.
Version:

Multi Environment

Pimcore supports different configurations for different environments (dev, test, stage, prod, ...) as well as custom configurations including a fallback mechanism.

The PIMCORE_ENVIRONMENT variable

To switch to a different environment, you have to set the environment variable PIMCORE_ENVIRONMENT with a value of your choice (eg. development or test). PIMCORE_ENVIRONMENT is an equivalent of Symfony's standard SYMFONY_ENV so you can use whatever you prefer.

Having the variable set, there is a special loading order for all configuration files.

Loading example for PIMCORE_ENVIRONMENT = dev:

app/config/pimcore/system_dev.php
var/config/system_dev.php
app/config/pimcore/system.php
var/config/system.php

The value of PIMCORE_ENVIRONMENT is used as a part of the file name separated by _. If you haven't set the environment variable, the loading order of configuration files looks like, below.

app/config/pimcore/system.php
var/config/system.php

Note: If you put your configurations into app/config/pimcore/ they might not writable by the Pimcore backend UI. This can be especially useful when having automated building environments and don't want the user to allow changing settings.

Set a new Environment name

If you need add a new environment which is not an existing one by default (those are prod, dev and test) you need to manually create a config file for the project in app/config/config_<environment>.yml.

Note: The default test environment should only be used for running tests as it is configured to handle sessions with the session.storage.mock_file. As consequence, logging into the admin interface is not possible in a browser context.

To create a new config, e.g. staging, which is based on the dev config, you must set staging as PIMCORE_ENVIRONMENT and create the following config file app/config/config_staging.yml:

imports:
    - { resource: '@PimcoreCoreBundle/Resources/config/pimcore/dev.yml' } # loads default dev configuration
    - { resource: config.yml }

By default, dev-bundles as the profiler are restricted to the dev environment. If you want to load those bundles in your environment, you need to modify the kernel in app\AppKernel.php to include those bundles in your environment. Have a look at the Pimcore Kernel to see what is loaded in the default dev environment.

For instance for an new environment called staging using web profiler, you can add something like the following:

<?php

use Pimcore\HttpKernel\BundleCollection\BundleCollection;
use Pimcore\Kernel;

class AppKernel extends Kernel
{
    public function registerBundlesToCollection(BundleCollection $collection)
    {
        $collection->addBundle(new \AppBundle\AppBundle);
    }

    protected function getEnvironmentsForDevBundles(): array
    {
        // override environments which should add dev bundles (e.g. the profiler)
        return ['dev', 'test', 'staging'];
    }
}

If you set PIMCORE_ENVIRONMENT to a new environment name before installation, all those steps need to be done before running the installation.

Setting the Environment

There are several ways to set the value of PIMCORE_ENVIRONMENT - depending on the environment and context you are using.

Apache mod_php

Add the following line to the virtual host configuration file.

SetEnv PIMCORE_ENVIRONMENT dev

PHP FPM

Add the following line to your pool.d configuration file.

env[PIMCORE_ENVIRONMENT] = "dev"

CLI

If you used a Unix system you would set the variable by CLI, like below.

PIMCORE_ENVIRONMENT="dev"; export PIMCORE_ENVIRONMENT

Console Commands

When running ./bin/console application, set the environment by --env=dev.

./bin/console --env=dev ...

.env

Pimcore loads a .env file if it exists. See DotEnv Component Documentation for details.

# .env
PIMCORE_ENVIRONMENT=dev

Switching Environments Dynamically

Add this to your .htaccess to switch dynamically between your environments:

RewriteCond %{HTTP_HOST} ^localhost
RewriteRule .? - [E=PIMCORE_ENVIRONMENT:dev]
RewriteCond %{HTTP_HOST} ^staging\.site\.com$
RewriteRule .? - [E=PIMCORE_ENVIRONMENT:stage]
RewriteCond %{HTTP_HOST} ^www\.site\.com
RewriteRule .? - [E=PIMCORE_ENVIRONMENT:prod]

Debug Mode & Environments

In order to include some specific debugging tools (profiler, toolbar, ...), Pimcore implicitly sets the environment to dev when enabling the debug mode in system settings and if no environment is defined manually as described above.

Influencing default behaviour

Pimcore ships with sensible defaults on which environment to use in which case, e.g. by automatically using the dev environment if Pimcore is in debug mode and by automatically enabling the kernel debug flag for the dev and test environments. If you need to influence that behaviour (e.g. because you have additional environments) you can do so by changing the environment config during the startup process. For example, if you want to specify the default environment to use when Pimcore's debug mode is enabled by no environment is explicitely defined:

<?php

// /app/startup.php

/** @var \Pimcore\Config\EnvironmentConfig $environmentConfig */
$environmentConfig = \Pimcore\Config::getEnvironmentConfig();
$environmentConfig->setDefaultDebugModeEnvironment('prod');

Supported Configurations

For examples, please see: