You are browsing the documentation for version 3.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

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 Oro\Bundle\ConfigBundle\DependencyInjection\SettingsBuilder in the Configuration class:

 1// src/Acme/DemoBundle/DependencyInjection/Configuration.php
 2namespace Acme\DemoBundle\DependencyInjection;
 4use Oro\Bundle\ConfigBundle\DependencyInjection\SettingsBuilder;
 5use Symfony\Component\Config\Definition\Builder\TreeBuilder;
 6use Symfony\Component\Config\Definition\ConfigurationInterface;
 8class Configuration implements ConfigurationInterface
10    public function getConfigTreeBuilder()
11    {
12        $treeBuilder = new TreeBuilder();
13        $rootNode = $treeBuilder->root('acme_demo');
15        // provide your regular Symfony configuration here
17        SettingsBuilder::append($rootNode, [
18            'foo' => [
19                'value' => true,
20                'type' => 'boolean',
21            ],
22            'bar' => [
23                'value' => 10,
24            ],
25        ]);
27        return $treeBuilder;
28    }

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:

 1# Acme/DemoBundle/Resources/config/oro/system_configuration.yml
 3    fields:
 4        foo:
 5            type: checkbox
 6            options:
 7                label: "A label"
 8            priority: 10
 9        bar:
10            type: text
11            priority: 20
12            tooltip: "A tooltip"

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




The form type (required)


Additional options that are passed to the form type


A tooltip containing additional information


ACL resource the user needs to be allowed to change the option


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:

 1// src/Acme/DemoBundle/Controller/DemoController.php
 2namespace Acme\DemoBundle\Controller;
 4use Symfony\Bundle\FrameworkBundle\Controller\Controller;
 6class DemoController extends Controller
 8    public function demoAction()
 9    {
10        $config = $this->get('oro_config.user');
11        $foo = $config->get('');
13        // ...
14    }


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:

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


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