System Configuration

With the OroConfigBundle you can define configuration settings in different scopes. These settings can be organized and visualized in different configuration trees.

Managing Configuration Settings

To define your own configuration settings in a bundle, you use the SettingsBuilder in the well-known Configuration class:

// src/Acme/DemoBundle/DependencyInjection/Configuration.php
namespace Acme\DemoBundle\DependencyInjection;

use Oro\Bundle\ConfigBundle\DependencyInjection\SettingsBuilder;
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
use Symfony\Component\Config\Definition\ConfigurationInterface;

class Configuration implements ConfigurationInterface
    public function getConfigTreeBuilder()
        $treeBuilder = new TreeBuilder();
        $rootNode = $treeBuilder->root('acme_demo');

        // provide your regular Symfony configuration here

        SettingsBuilder::append($rootNode, [
            'foo' => [
                'value' => true,
                'type' => 'boolean',
            'bar' => [
                'value' => 10,

        return $treeBuilder;

The SettingsBuilder class is a helper class that adds additional nodes to the configuration tree. It expects the root node of the tree to which the new nodes are appended. The second argument is an array of configuration settings. The example above adds two options: foo and bar. Each option can get a default value and a type (one of scalar, boolean or array). The default type if none is specified is scalar.

See also

If you are not familiar with creating Configuration classes, read about semantic configurations in the official documentation.

Creating Configuration Forms

To allow a user to modify their configuration settings, you have to create a form that is presented to the user. The form configuration is done in the system_configuration.yml file of the bundle.


For each option, define a field under fields key:

# Acme/DemoBundle/Resources/config/oro/system_configuration.yml
            type: checkbox
                label: "A label"
            priority: 10
            type: text
            priority: 20
            tooltip: "A tooltip"

The only required field is type which can refer to any valid form type. Other supported fields are:

Field Description
type The form type (required)
options Additional options that are passed to the form type
tooltip A tooltip containing additional information
acl_resource ACL resource the user needs to be allowed to change the option
priority Optional field display order

Accessing Configuration Values

In Controllers

To retrieve configuration values inside a controller, you have to use the oro_config.user service which is an instance of Oro\ConfigBundle\Config\UserConfigManager. Use its get() method to retrieve the value of a setting:

// src/Acme/DemoBundle/Controller/DemoController.php
namespace Acme\DemoBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class DemoController extends Controller
    public function demoAction()
        $config = $this->get('oro_config.user');
        $foo = $config->get('');

        // ...


The actual setting name is to be prefixed by the bundle alias (here acme_demo for AcmeDemoBundle).

In Templates

In a Twig template, use the oro_config_value() helper to retrieve the value of a configuration option:

{# setting becomes the value the user configured or true if they didn't #}
{% set setting = oro_config_value('') %}


The actual setting name is to be prefixed by the bundle alias (here acme_demo for AcmeDemoBundle).