You are browsing documentation for version 5.0 of OroCommerce, OroCRM, and OroPlatform, maintained until August 2024 and supported until March 2026. 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.
The configuration extras are the way to get varying configuration information.
There are two types of configuration extras:
A configuration extra used to request additional configuration options for existing configuration sections. This extra is represented by
A configuration extra used to request additional configuration sections. This extra is represented by
Both types of configuration extras work in the following way:
The actions like get, get_list or delete register the configuration extras in the context using the
addConfigExtramethod. All required extras must be registered before any of the
getConfigOfSortersmethods of the Context is called. Typically the registration happens in processors from the
initializegroup. For example, InitializeConfigExtras.
When a processor needs a configuration, it calls the appropriate method of the context. For example
getConfigOfSorters. The first call of any of these methods causes the loading of the configuration.
The loading of the configuration is performed by the get_config action. Any processors registered for this action can check which configuration data is requested. There are two ways a processor can find out which configuration data is requested. The first one is to use the processor conditions. The second one is to use the
hasExtramethod of the ConfigContext.
For more details on the config structure, sections, properties, etc., see the Configuration Reference.
The ConfigExtraInterface has the following methods:
getName - Returns a string which is used as unique identifier of configuration data.
getCacheKeyPart - Returns a string to add to a cache key used by the configuration providers. In most cases, this method returns the same value as the
getNamemethod. However, more complicated extras can build the cache key part based on other properties, e.g., MaxRelatedEntitiesConfigExtra.
configureContext - Adds additional values into the ConfigContext. For example, the mentioned above MaxRelatedEntitiesConfigExtra adds the maximum number of related entities into the context of the get_config action, and this value is used by the SetMaxRelatedEntities processor to make necessary modifications to the configuration.
isPropagable - Indicates whether this config extra should be used when a configuration of related entities is built. For example, DescriptionsConfigExtra is propagable; as a result, field value data transformers will be returned for the main entity and all related entities.
getConfigType - Returns the configuration type that should be loaded into the corresponding section. The ConfigLoaderFactory uses the return value of this method to find the appropriate loader.
There is a list of existing configuration extras that implement this interface:
The DescriptionsConfigExtra is used to request human-readable descriptions of entities and their fields:
class DescriptionsConfigExtra implements ConfigExtraInterface
public const NAME = 'descriptions';
public function getName()
public function configureContext(ConfigContext $context)
// no modifications of the ConfigContext are required
public function isPropagable()
public function getCacheKeyPart()
Usually, configuration extras are added to the context by the
InitializeConfigExtras processors, which belong to the
initialize group, e.g., the InitializeConfigExtras processor for the
get action. However, the API documentation requires human-readable descriptions. Therefore, DescriptionsConfigExtra is added by RestDocHandler.
The CompleteDescriptions processor adds entities, fields, and filter descriptions. This processor is registered as a service in processors.get_config.yml. Note that the processor tag contains the
extra attribute with the
descriptions&definition value. This means that the processor will be executed only if the extra configuration (in this case,
definition) were requested. For more details, see processor conditions.