Skip to content

Configuration

eZ Platform configuration is delivered using a number of dedicated configuration files. It contains everything from selecting the content Repository to SiteAccesses to language settings.

Configuration format

The recommended configuration format is YAML. It is used by default in the kernel (and in examples throughout the documentation). However, you can also use XML or PHP formats for configuration.

Configuration files

Main configuration files are located in the app/config folder.

  • parameters.yml contains infrastructure-related configuration. It is created based on the default settings defined in parameters.yml.dist.
  • config.yml contains configuration stemming from Symfony and covers settings such as search engine or cache configuration.
  • ezplatform.yml contains general configuration that is specific for eZ Platform, like for example SiteAccess settings.
  • security.yml is the place for security-related settings.
  • routing.yml defines routes that will be used throughout the application.

Configuration can be made environment-specific using separate files for each environment. These files contain additional settings and point to the general (not environment-specific) configuration that is applied in other cases.

Here you can read more about how configuration is handled in Symfony.

Configuration handling

Note

Configuration is tightly related to the service container. To fully understand it, you need to be familiar with Symfony's service container and its configuration.

Basic configuration handling in eZ Platform is similar to what is commonly possible with Symfony. You can define key/value pairs in your configuration files, under the main parameters key (see for example parameters.yml).

Internally and by convention, keys follow a dot syntax, where the different segments follow your configuration hierarchy. Keys are usually prefixed by a namespace corresponding to your application. All kinds of values are accepted, including arrays and deep hashes.

For configuration that is meant to be exposed to an end-user (or end-developer), it's usually a good idea to also implement semantic configuration.

Note that you can also implement SiteAccess-aware semantic configuration.

Example

1
2
3
4
5
6
parameters:
    myapp.parameter.name: someValue
    myapp.boolean.param: true
    myapp.some.hash:
        foo: bar
        an_array: [apple, banana, pear]
1
2
// Usage inside a controller
$myParameter = $this->container->getParameter( 'myapp.parameter.name' );

Dynamic configuration with the ConfigResolver

In eZ Platform it is fairly common to have different settings depending on the current SiteAccess (e.g. languages, view provider configuration).

ConfigResolver Usage

Dynamic configuration is handled by a config resolver. It consists in a service object mainly exposing hasParameter() and getParameter() methods. The idea is to check the different scopes available for a given namespace to find the appropriate parameter.

In order to work with the config resolver, your dynamic settings must comply internally with the following name format: <namespace>.<scope>.parameter.name.

The following configuration is an example of internal usage inside the code of eZ Platform:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Namespace + scope example
parameters:
    # Some internal configuration
    ezsettings.default.content.default_ttl: 60
    ezsettings.ezdemo_site.content.default_ttl: 3600
 
    # Here "myapp" is the namespace, followed by the SiteAccess name as the parameter scope
    # Parameter "foo" will have a different value in ezdemo_site and ezdemo_site_admin
    myapp.ezdemo_site.foo: bar
    myapp.ezdemo_site_admin.foo: another value
    # Defining a default value, for other SiteAccesses
    myapp.default.foo: Default value
 
    # Defining a global setting, used for all SiteAccesses
    #myapp.global.some.setting: This is a global value
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
// Inside a controller, assuming SiteAccess being "ezdemo_site"
/** @var $configResolver \eZ\Publish\Core\MVC\ConfigResolverInterface **/
$configResolver = $this->getConfigResolver();
 
// ezsettings is the default namespace, so no need to specify it
// The following will resolve ezsettings.<siteaccessName>.content.default_ttl
// In the case of ezdemo_site, will return 3600.
// Otherwise it will return the value for ezsettings.default.content.default_ttl (60)
$locationViewSetting = $configResolver->getParameter( 'content.default_ttl' );
 
$fooSetting = $configResolver->getParameter( 'foo', 'myapp' );
// $fooSetting's value will be 'bar'
 
// Force scope
$fooSettingAdmin = $configResolver->getParameter( 'foo', 'myapp', 'ezdemo_site_admin' );
// $fooSetting's value will be 'another value'
 
// Note that the same applies for hasParameter()

Both getParameter() and hasParameter() can take 3 different arguments:

  1. $paramName (the name of the parameter you need)
  2. $namespace (your application namespace, myapp in the previous example. If null, the default namespace will be used, which is ezsettings by default)
  3. $scope (a SiteAccess name. If null, the current SiteAccess will be used)

Inject the ConfigResolver in your services

Instead of injecting the whole ConfigResolver service, you may directly inject your SiteAccess-aware settings (aka dynamic settings) into your own services.

You can use the ConfigResolver in your own services whenever needed. To do this, just inject the ezpublish.config.resolver service:

1
2
3
4
5
6
7
parameters:
    my_service.class: My\Cool\Service
 
services:
    my_service:
        class: %my_service.class%
        arguments: [@ezpublish.config.resolver]
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
<?php
namespace My\Cool;
 
use eZ\Publish\Core\MVC\ConfigResolverInterface;
 
class Service
{
    /**
     * @var \eZ\Publish\Core\MVC\ConfigResolverInterface
     */
    private $configResolver;
 
    public function __construct( ConfigResolverInterface $configResolver )
    {
        $this->configResolver = $configResolver;
        $myParam = $this->configResolver->getParameter( 'foo', 'myapp' );
    }
 
    // ...
}

Dynamic Settings Injection

When implementing a service needing SiteAccess-aware settings (e.g. language settings), you can inject these dynamic settings explicitly from their service definition (yml, xml, annotation, etc.).

Syntax

Static container parameters follow the %<parameter_name>% syntax in Symfony.

Dynamic parameters have the following: $<parameter_name>[; <namespace>[; <scope>]]$, default namespace being ezsettings, and default scope being the current SiteAccess.

For more information, see ConfigResolver.

DynamicSettingParser

The DynamicSettingParser service that can be used for adding support of the dynamic settings syntax. This service has ezpublish.config.dynamic_setting.parser for ID and implementseZ\Bundle\EzPublishCoreBundle\DependencyInjection\Configuration\SiteAccessAware\DynamicSettingParserInterface.

Limitations

  • It is not possible to use dynamic settings in your semantic configuration (e.g. config.yml or ezplatform.yml) as they are meant primarily for parameter injection in services.
  • It is not possible to define an array of options having dynamic settings. They will not be parsed. Workaround is to use separate arguments/setters.
  • Injecting dynamic settings in request listeners is not recommended, as it won't be resolved with the correct scope (request listeners are instantiated before SiteAccess match). Workaround is to inject the ConfigResolver instead, and resolve the setting in your onKernelRequest method (or equivalent).

Examples

Injecting an eZ parameter

Defining a simple service needing a languages parameter (that is, prioritized languages).

Note

Internally, the languages parameter is defined as ezsettings.<siteaccess_name>.languages, ezsettings being eZ internal namespace.

Using setter injection (preferred)
1
2
3
4
5
6
7
8
parameters:
    acme_test.my_service.class: Acme\TestBundle\MyServiceClass

services:
    acme_test.my_service:
        class: %acme_test.my_service.class%
        calls:
            - [setLanguages, ["$languages$"]]
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
namespace Acme\TestBundle;

class MyServiceClass
{
    /**
 * Prioritized languages
 *
 * @var array
 */
    private $languages;

    public function setLanguages( array $languages = null )
    {
        $this->languages = $languages;
    }
}

Caution

Ensure you always add null as a default value, especially if the argument is type-hinted.

Using constructor injection
1
2
3
4
5
6
7
parameters:
    acme_test.my_service.class: Acme\TestBundle\MyServiceClass

services:
    acme_test.my_service:
        class: %acme_test.my_service.class%
        arguments: ["$languages$"]
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
namespace Acme\TestBundle;

class MyServiceClass
{
    /**
 * Prioritized languages
 *
 * @var array
 */
    private $languages;

    public function __construct( array $languages )
    {
        $this->languages = $languages;
    }
}

Tip

Setter injection for dynamic settings should always be preferred, as it makes it possible to update your services that depend on them when ConfigResolver is updating its scope (e.g. when previewing content in a given SiteAccess). However, only one dynamic setting should be injected by setter.

Constructor injection will make your service be reset in that case.

Injecting third party parameters
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
parameters:
    acme_test.my_service.class: Acme\TestBundle\MyServiceClass
    # "acme" is our parameter namespace.
    # Null is the default value.
    acme.default.some_parameter: ~
    acme.ezdemo_site.some_parameter: foo
    acme.ezdemo_site_admin.some_parameter: bar
 
services:
    acme_test.my_service:
        class: %acme_test.my_service.class%
        # The following argument will automatically resolve to the right value, depending on the current SiteAccess.
        # We specify "acme" as the namespace we want to use for parameter resolving.
        calls:
            - [setSomeParameter, ["$some_parameter;acme$"]]
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
namespace Acme\TestBundle;
class MyServiceClass
{
    private $myParameter;
    public function setSomeParameter( $myParameter = null )
    {
        // Will be "foo" for ezdemo_site, "bar" for ezdemo_site_admin, or null if another SiteAccess.
        $this->myParameter = $myParameter;
    }
}

Content Repository configuration

The default storage engine for the Repository is called Legacy storage engine.

You can define several Repositories within a single application. However, you can only use one per site.

Configuration examples

Using default values

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# ezplatform.yml
ezpublish:
    repositories:
        # Defining Repository with alias "main"
        # Default storage engine is used, with default connection
        # Equals to:
        # main: { storage: { engine: legacy, connection: <defaultConnectionName> } }
        main: ~

    system:
        # All members of my_siteaccess_group will use "main" Repository
        # No need to set "repository", it will take the first defined Repository by default
        my_siteaccess_group:
            # ...

If no Repository is specified for a SiteAccess or SiteAccess group, the first Repository defined under ezpublish.repositories will be used.

All explicit

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# ezplatform.yml
doctrine:
    dbal:
        default_connection: my_connection_name
        connections:
            my_connection_name:
                driver:   pdo_mysql
                host:     localhost
                port:     3306
                dbname:   my_database
                user:     my_user
                password: my_password
                charset:  UTF8

            another_connection_name:
                # ...

ezpublish:
    repositories:
        first_repository: { storage: { engine: legacy, connection: my_connection_name, config: {} } }
        second_repository: { storage: { engine: legacy, connection: another_connection_name, config: {} } }

    # ...

    system:
        my_first_siteaccess:
            repository: first_repository

            # ...

        my_second_siteaccess:
            repository: second_repository

Legacy storage engine

Legacy storage engine uses Doctrine DBAL (Database Abstraction Layer). Database settings are supplied by DoctrineBundle. As such, you can refer to DoctrineBundle's documentation.

ORM

Doctrine ORM is not provided by default. If you want to use it, you will need to add doctrine/orm as a dependency in your composer.json.

Field groups configuration

Field groups, used in content and Content Type editing, can be configured from the repositories section. Values entered there are field group identifiers:

1
2
3
4
5
repositories:
    default:
        fields_groups:
            list: [content, features, metadata]
            default: content

These identifiers can be given human-readable values and translated. Those values are used when editing Content Types. The translation domain is ezplatform_fields_groups. This file will define English names for field groups:

1
2
3
4
# app/Resources/translations/ezplatform_fields_groups.en.yml
content: Content
metadata: Metadata
user_data: User data

Limit of archived Content item versions

default_version_archive_limit controls the number of archived versions per Content item that will be stored in the Repository, by default set to 5. This setting is configured in the following way (typically in ezplatform.yml):

1
2
3
4
5
ezpublish:
    repositories:
        default:
            options:
                default_version_archive_limit: 10

This limit is enforced on publishing a new version and only covers archived versions, not drafts.

Tip

Don't set default_version_archive_limit too high, with Legacy storage engine you'll get performance degradation if you store too many versions. Default value of 5 is in general the recommended value, but the less content you have overall, the more you can increase this to, for instance, 25 or even 50.

Back Office configuration

Default page

You can define the default page that will be shown after user login. This overrides Symfony's default_target_path, and enables you to configure redirection per SiteAccess.

1
2
3
4
5
6
7
8
ezpublish:
    system:
        ezdemo_site:
            default_page: "/Getting-Started"

        ezdemo_site_admin:
            # For admin, redirect to dashboard after login.
            default_page: "/content/dashboard"

This setting does not change Symfony behavior regarding redirection after login. If set, it will only substitute the value set for default_target_path. It is therefore still possible to specify a custom target path using a dedicated form parameter.

Order of precedence is not modified.

Copy subtree limit

Copying large subtrees can cause performance issues, so you can limit the number of Content items that can be copied at once using ezsystems.platformui.application_config.copy_subtree.limit in parameters.yml.

The default value is 100. You can set it to -1 for no limit, or to 0 to completely disable copying subtrees.

Pagination limits

Default pagination limits for different sections of the Back Office are defined in the following settings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
ezsettings.default.pagination.search_limit: 10
ezsettings.default.pagination.trash_limit: 10
ezsettings.default.pagination.section_limit: 10
ezsettings.default.pagination.language_limit: 10
ezsettings.default.pagination.role_limit: 10
ezsettings.default.pagination.content_type_group_limit: 10
ezsettings.default.pagination.content_type_limit: 10
ezsettings.default.pagination.role_assignment_limit: 10
ezsettings.default.pagination.policy_limit: 10
ezsettings.default.pagination.version_draft_limit: 5

Other configuration

The configuration related to other specific topics is described in:

Read the Docs