Important

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.

Configure Entities

So far, Doctrine offers a wide range of functionality to map your entities to the database, to save your data and to retrieve them from the database. However, in an application based on the Oro Platform, you usually want to control how entities are presented to the user. OroPlatform includes the EntityConfigBundle that makes it easy to configure additional metadata of your entities as well as the fields of your entities. For example, you can now configure icons and labels used when showing an entity in the UI or you can set up access levels to control how entities can be viewed and modified.

Configure Entities and Their Fields

Entities will not be configurable by default. They must be tagged as configurable entities to let the system apply entity config options to them:

  • The @Config annotation is used to enable entity level configuration for an entity.

  • Use the @ConfigField annotation to enable config options for selected fields.

Tip

The bundles from OroPlatform offer a large set of predefined options that you can use in your entities to configure them and control their behavior. Take a look at the entity_config.yml files that can be found in many bundles and read their dedicated documentation.

The @Config Annotation

To make the Hotel entity from the first part of the chapter configurable, simply import the Oro\Bundle\EntityConfigBundle\Metadata\Annotation\Config annotation and use it in the class docblock:

 1// src/Acme/DemoBundle/Entity/Hotel.php
 2namespace Acme\DemoBundle\Entity;
 3
 4use Doctrine\ORM\Mapping as ORM;
 5use Oro\Bundle\EntityConfigBundle\Metadata\Annotation\Config;
 6
 7/**
 8 * @ORM\Entity
 9 * @ORM\Table(name="acme_hotel")
10 * @Config
11 */
12class Hotel
13{
14    // ...
15}

You can also change the default value of each configurable option using the defaultValues argument:

 1// src/Acme/DemoBundle/Entity/Hotel.php
 2namespace Acme\DemoBundle\Entity;
 3
 4use Doctrine\ORM\Mapping as ORM;
 5use Oro\Bundle\EntityConfigBundle\Metadata\Annotation\Config;
 6
 7/**
 8 * @ORM\Entity
 9 * @ORM\Table(name="acme_hotel")
10 * @Config(
11 *     defaultValues={
12 *         "acme_demo"={
13 *             "comment"="Our hotels"
14 *         }
15 *     }
16 * )
17 */
18class Hotel
19{
20    // ...
21}

The @ConfigField Annotation

Similar to the @Config annotation for entities, you can use the Oro\Bundle\EntityConfigBundle\Metadata\Annotation\ConfigField annotation to make properties of an entity configurable:

 1// src/Acme/DemoBundle/Entity/Hotel.php
 2namespace Acme\DemoBundle\Entity;
 3
 4use Doctrine\ORM\Mapping as ORM;
 5use Oro\Bundle\EntityConfigBundle\Metadata\Annotation\ConfigField;
 6
 7/**
 8 * @ORM\Entity
 9 * @ORM\Table(name="acme_hotel")
10 */
11class Hotel
12{
13    // ...
14
15    /**
16    * @ORM\Column(type="string", length=255)
17    * @ConfigField
18    */
19    private $name;
20
21    // ...
22}

Default values can be changed in the same way as it can be done on the entity level:

 1// src/Acme/DemoBundle/Entity/Hotel.php
 2namespace Acme\DemoBundle\Entity;
 3
 4use Doctrine\ORM\Mapping as ORM;
 5use Oro\Bundle\EntityConfigBundle\Metadata\Annotation\ConfigField;
 6
 7/**
 8 * @ORM\Entity
 9 * @ORM\Table(name="acme_hotel")
10 */
11class Hotel
12{
13    // ...
14
15    /**
16    * @ORM\Column(type="string", length=255)
17    * @ConfigField(
18    *     "defaultValues"={
19    *         "acme_demo"={
20    *             "auditable"=true
21    *         }
22    *     }
23    * )
24    */
25    private $name;
26
27    // ...
28}

Add Configuration Options

In the first step, you need to define the options that should be configurable. New options can be created per bundle which means that a bundle can extend the set of available options. To add new options, you create a entity_config.yml file in your bundle which can look like this:

 1# src/Acme/DemoBundle/Resources/config/oro/entity_config.yml
 2entity_config:
 3    acme_demo:
 4        entity:
 5            items:
 6                comment:
 7                    options:
 8                        default_value: ""
 9                        translatable:  true
10                        indexed:       true
11                    grid:
12                        type:        string
13                        label:       Comment
14                        show_filter: true
15                        filterable:  true
16                        filter_type: string
17                        sortable:    true
18                    form:
19                        type: text
20                        options:
21                            block: entity
22                            label: Comment
23        field:
24            items:
25                auditable:
26                    options:
27                        indexed:  true
28                        priority: 60
29                    grid:
30                        type:        boolean
31                        label:       'Auditable'
32                        show_filter: false
33                        filterable:  true
34                        filter_type: boolean
35                        sortable:    true
36                        required:    true
37                    form:
38                        type: choice
39                        options:
40                            block:       entity
41                            label:       'Auditable'
42                            choices:     ['No', 'Yes']
43                            empty_value: false

The key used in the first level of the entity configuration is a custom identifier used to create a kind of namespace for the additional options. For each scope, a different service is created (its name follows the schema oro_entity_config.provider.<scope>). For example, the service name for the options configured in the example above is oro_entity_config.provider.acme_demo. It is an instance of the Oro\Bundle\EntityConfigBundle\Provider\ConfigProvider class.

Options can be configured on two levels: on the entity level or per field. The example above adds a new comment property that allows the users to add custom comments per configurable entity. It also adds the auditable option on the field level. This means that the user can decide for every field on an entity whether or not it should be audited.

The configured values are stored in different tables:

  • Values for options on the entity level are stored in the oro_entity_config table.

  • The oro_entity_config_field table is used to store configured values for the field level.

Below the configuration level, each option’s configuration is divided into three sections:

options

These values are used to configure additional behavior for the config field:

Option

Description

default_value

The value that is used by default when no custom value was added.

translatable

If true, the value entered by the user is treated as a key which is then used to look up the actual value using the Symfony translation procedure.

indexed

Set this to true when the attribute needs to be accessed in SQL queries (see Indexed Attributes).

priority

Defines the order in which options will be shown in grid views and forms (options with a higher priority will be displayed before options with a lower priority).
grid

Configures the way the field is presented in a datagrid:

Option

Description

type

The attribute type

label

The grid column headline

  • show_filter

  • filterable

  • filter_type

These options control whether the view can be filtered by the attribute value and how the filter options look like.

sortable

When enabled, the user can sort the table by clicking on the attribute column’s title.

Note

In order to use the attribute in a grid view, it needs to be indexed.

form

You use these options to control how the actual value can be configured by the user:

Option

Description

type

The form type

options

Additional options controlling the form layout:

  • block

The block of the form in which the attribute will be displayed

  • label

The field label

  • choices

Possible values from which the user can choose one (this option is only available when the form type is choice)

  • empty_value

The value that is taken when the user makes no choice (this option is only available when the form type is choice)

Secondly, you need to update all configurable entities after configuration parameters have been modified or added using the oro:entity-config:update command:

$ php bin/console oro:entity-config:update --force

When the oro:entity-config:update command is executed without using the --force option, only new values will be added, but no existing parameters will be updated.

Indexed Attributes

By default, the values the user enters when editing additional entity attributes are stored as serialized arrays in the database. However, when the application needs to use attributes in an SQL query, it needs to get the raw data. To achieve this, you have to enable the index using the indexed key in the options section. When this option is enabled, the system will store a copy of the attributes value and keep it in sync when it gets updated (the indexed value is stored in the oro_entity_config_index_value table).

Access Entities Configuration

Now that you know how you define additional configuration options and how to use them in your own entities, you will usually want to access the configured values. The main entry point to access the configuration is the provider service for the particular scope which has to be retrieved from the service container. For example, if you want to work with your newly created auditable option, you will have to use the oro_entity_config.provider.acme_demo service (the auditable option was defined in the acme_demo scope):

1// $container is an instance of Symfony\Component\DependencyInjection\ContainerInterface
2$container = ...;
3$acmeDemoProvider = $container->get('oro_entity_config.provider.acme_demo');

Then you need to fetch the configuration in this scope for a particular entity or entity field using the Oro\Bundle\EntityConfigBundle\Provider\ConfigProvider::getConfig() method. The configuration for such a configurable object (an entity or a field) is represented by an instance of the Oro\Bundle\EntityConfigBundle\Config\ConfigInterface:

get()

Returns the actually configured value for an option.

set()

Changes the value of an option to a new value.

remove()

Removes the particular option.

has()

Checks whether or not an option with the given name exists.

is()

Checks if the value of an option equals the given value.

in()

Checks if the value of an option is one of the given values.

all()

Returns all parameters for the configurable object.

setValues()

Replaces values for the given options with some given values.

Please note that it is not enough to modify configuration values in the provider. You also need to persist your changes by calling the Oro\Bundle\EntityConfigBundle\Provider\ConfigProvider::flush method afterwards:

1// ...
2$acmeDemoProvider = $container->get('oro_entity_config.provider.acme_demo');
3$acmeConfig = $acmeDemoProvider->getConfig('Acme\Bundle\AcmeBundle\Entity\Hotel');
4$acmeConfig->set('comment', 'Updated comment');
5$acmeDemoProvider->getConfigManager()->flush();

Tip

Use the oro:entity-config:debug command to access or modify configuration values from the command line.