Configuration Extras¶
Overview¶
The configuration extras are the way to get varying configuration information.
There are two types of the configuration extras:
- a configuration extra that is used to request additional configuration options for existing configuration sections. This extra is represented by
Oro\Bundle\ApiBundle\Config\ConfigExtraInterface
. - a configuration extra that is used to request additional configuration section. This extra is represented by
Oro\Bundle\ApiBundle\Config\ConfigExtraSectionInterface
.
The both types of the configuration extras works in the following way:
- The actions like get, get_list or delete register the configuration extras in the Context using the
addConfigExtra
method. All required extras must be registered before any of thegetConfig
,getConfigOf
,getConfigOfFilters
orgetConfigOfSorters
methods of the Context is called. Typically the registration happens in processors frominitialize
group. For example InitializeConfigExtras. - When some processor needs a configuration it calls appropriate method of the Context. For example
getConfig
,getConfigOf
,getConfigOfFilters
orgetConfigOfSorters
. 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 of processors registered for this action can check which configuration data is requested and will do suitable work. There are two ways how a processor can find out which configuration data is requested. The first is to use the processor conditions. The second one is to use the
hasExtra
method of the ConfigContext.
Also, please take a look into Configuration Reference for more details about config structure, sections, properties etc.
ConfigExtraInterface¶
The ConfigExtraInterface has the following methods:
- getName – Returns a string which is used as unique identifier of configuration data.
- getCacheKeyPart – Returns a string that should be added to a cache key used by configuration providers. In most cases this method returns the same value as the
getName
method. But some more complicated extras can build the cache key part based on own properties, e.g. MaxRelatedEntitiesConfigExtra. - configureContext – This method can be used to add 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 will be built. For example DescriptionsConfigExtra is propagable and it means that we will get human-readable descriptions of main entity and all the related entities. If this extra was not propagable the descriptions of main entity would be returned.
ConfigExtraSectionInterface¶
The ConfigExtraSectionInterface extends ConfigExtraInterface and has one additional method:
- getConfigType – Returns the configuration type that should be loaded into this section. This string is used by ConfigLoaderFactory to find the appropriate loader.
There is a list of existing configuration extras that implement this interface:
Example of configuration extra¶
Let’s take a look into DescriptionsConfigExtra which is used to request human-readable descriptions of entities and its’ fields.
<?php
namespace Oro\Bundle\ApiBundle\Config;
use Oro\Bundle\ApiBundle\Processor\Config\ConfigContext;
class DescriptionsConfigExtra implements ConfigExtraInterface
{
const NAME = 'descriptions';
public function getName()
{
return self::NAME;
}
public function configureContext(ConfigContext $context)
{
// no any modifications of the ConfigContext is required
}
public function isPropagable()
{
return true;
}
public function getCacheKeyPart()
{
return self::NAME;
}
}
Usually configuration extras are added to the Context by InitializeConfigExtras
processors which belong to initialize
group, e.g. InitializeConfigExtras processor for get
action. But human-readable descriptions are required only for generation documentation for Data API. So, DescriptionsConfigExtra is added by RestDocHandler.
The processor which adds descriptions for entity, fields and filters is CompleteDescriptions. This processor is registered as services in processors.get_config.yml. Please note, the processor tag contains the extra
attribute with descriptions&definition
value. This means that the processor will be executed only if the
extra configuration (in this case description
and definition
) were requested. For more details see processor conditions.