Important

You are browsing the documentation for version 4.2 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.

Feature Toggle

Define a New Feature

Features are defined in configuration files placed into Resources/config/oro/features.yml.

Each feature consists of one required option, the label. You can configure the following sections, out-of-the-box:

  • label - a feature title

  • description - a feature description

  • toggle - a system configuration option key that is used as a feature toggle

  • dependencies - a list of feature names that the current feature depends on

  • routes - a list of route names

  • configuration - a list of system configuration groups and fields

  • workflows - a list of workflow names

  • processes - a list of process names

  • operations - a list of operation names

  • api_resources - a list of entity FQCNs that are available as API resources

  • commands - a list of commands which depend on the feature. Running these commands is impossible or is not reasonable when the feature is disabled

  • entities - a list of entity FQCNs

  • field_configs - a list of field names

  • dashboard_widgets - a list of dashboard widget names

  • cron_jobs - a list of cron job names

  • navigation_items - a list of navigation items

  • placeholder_items - a list of placeholder item names

  • mq_topics - a list of MQ topic names

Example of the features.yml configuration

features:
    acme:
        label: acme.feature.label
        description: acme.feature.description
        toggle: acme.feature_enabled
        dependencies:
            - foo
            - bar
        routes:
            - acme_entity_view
            - acme_entity_create
        configuration:
            - acme_general_section
            - acme.some_option
        workflows:
            - acme_sales_flow
        processes:
            - acme_some_process
        operations:
            - acme_some_operation
        api_resources:
            - Acme\Bundle\Entity\Page
        commands:
            - oro:search:index
        entities:
            - Acme\Bundle\Entity\Page
        field_configs:
            - 'some_field_name'
        dashboard_widgets:
            - 'page_dashboard_widget'
        cron_jobs:
            - 'acme:cron:sync-job'
        navigation_items:
            - 'application_menu.sales_tab.acme_order_list'
        placeholder_items:
            - acme_create_page_button
        mq_topics:
            - 'acme.mq_topics.calculate'

Add New Options to Feature Configuration

Feature configuration may be extended with new configuration options. To add a new configuration option, you need to add a feature configuration that implements ConfigurationExtensionInterface and register it with the oro_feature.config_extension tag. For example, there are some Acme processors which should be configured with the acme_processor option.

Configuration extension:

namespace Acme\Bundle\ProcessorBundle\Config;

use Oro\Bundle\FeatureToggleBundle\Configuration\ConfigurationExtensionInterface;
use Symfony\Component\Config\Definition\Builder\NodeBuilder;

class FeatureConfigurationExtension implements ConfigurationExtensionInterface
{
    /**
     * {@inheritdoc}
     */
    public function extendConfigurationTree(NodeBuilder $node)
    {
        $node
            ->arrayNode('acme_processor')
                ->prototype('variable')
                ->end()
            ->end();
    }
}

Extension registration:

services:
    acme.configuration.feature_configuration_extension:
        class: Acme\Bundle\ProcessorBundle\Config\FeatureConfigurationExtension
        tags:
            - { name: oro_feature.config_extension }

Check Feature State

Feature state is determined by FeatureChecker. There are proxy classes that expose a feature check functionality to layout updates, operations, workflows, processes, and twig.

Feature state is resolved by isFeatureEnabled($featureName, $scopeIdentifier = null)

Feature resource types are nodes of feature configuration (routes, workflows, configuration, processes, operations, api_resources), resources are their values. Resource is disabled if it is included into at least one disabled feature. Resource state is resolved by public function isResourceEnabled($resource, $resourceType, $scopeIdentifier = null)

Layout Updates

  • Check the feature state =data[‘feature’].isFeatureEnabled(‘feature_name’)

  • Check the resource state =data[‘feature’].isResourceEnabled(‘acme_product_view’, ‘routes’)

Set the block visibility based on the feature state:

layout:
    actions:
        - '@add':
            id: products
            parentId: page_content
            blockType: datagrid
            options:
                grid_name: products-grid
                visible: '=data["feature"].isFeatureEnabled("product_feature")'

Processes, Workflows, Operations

In processes, workflows and operations, config expressions may be used to check the feature state

  • Check the feature state

    '@feature_enabled':
        feature: 'feature_name'
        scope_identifier: $.scopeIdentifier
    
  • Check the resource state

    '@feature_resource_enabled':
        resource: 'some_route'
        resource_type: 'routes'
        scope_identifier: $.scopeId
    

Twig

  • Check the feature state feature_enabled($featureName, $scopeIdentifier = null)

  • Check the resource state feature_resource_enabled($resource, $resourceType, $scopeIdentifier = null)

Include a Service Into a Feature

Any service that requires a feature functionality, needs to implement the FeatureToggleableInterface interface. All checks are done by developer.

OroFeatureToggleBundle provides helper functionality to inject a feature checker and a feature name into services marked with the oro_featuretogle.feature tag. FeatureCheckerHolderTrait contains implementation of methods from FeatureToggleableInterface.

Some extensions can extend the form, and we need to include this extension functionality into a feature. In this case, FeatureChecker should be injected into service, and feature availability should be checked where needed.

Extension:

namespace Acme\Bundle\CategoryBundle\Form\Extension;

use Symfony\Component\Form\AbstractTypeExtension;
use Symfony\Component\Form\FormBuilderInterface;

use Oro\Bundle\FeatureToggleBundle\Checker\FeatureToggleableInterface;
use Oro\Bundle\FeatureToggleBundle\Checker\FeatureCheckerHolderTrait;

class ProductFormExtension extends AbstractTypeExtension implements FeatureToggleableInterface
{
    use FeatureCheckerHolderTrait;

    /**
     * {@inheritdoc}
     */
    public static function getExtendedTypes(): iterable
    {
        return ['acme_product'];
    }

    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        if (!$this->isFeaturesEnabled()) {
            return;
        }

        $builder->add(
            'category',
            AcmeCategoryTreeType::class,
            [
                'required' => false,
                'mapped' => false,
                'label' => 'Category'
            ]
        );
    }
}

Extension registration:

services:
    acme_category.form.extension.product_form:
        class: Acme\Bundle\CategoryBundle\Form\Extension\ProductFormExtension
    tags:
        - { name: oro_featuretogle.feature, feature: acme_feature }

Check Feature State with a Feature Voter

Feature state is checked by feature voters. All voters are called each time you use the isFeatureEnabled() or isResourceEnabled() method on the feature checker. The feature checker makes the decision based on the configured strategy defined in the system configuration or per feature, which can be: affirmative, consensus, or unanimous.

By default, ConfigVoter is registered to check features availability. It checks the feature state based on the value of a toggle option defined in the features.yml configuration.

A custom voter needs to implement Oro\Bundle\FeatureToggleBundle\Checker\Voter\VoterInterface. Imagine that we have the state checker that returns decision based on a feature name and a scope identifier. The feature is enabled for the valid state and disabled for the invalid state. In other cases, do not vote.

Such voter looks as follows:

namespace Acme\Bundle\ProcessorBundle\Voter;

use Oro\Bundle\FeatureToggleBundle\Checker\Voter\VoterInterface;

class FeatureVoter implements VoterInterface
{
    private StateChecker $stateChecker;

    public function __construct(StateChecker $stateChecker) {
        $this->stateChecker = $stateChecker;
    }

    /**
     * @param string $feature
     * @param object|int|null $scopeIdentifier
     * return int either FEATURE_ENABLED, FEATURE_ABSTAIN, or FEATURE_DISABLED
     */
    public function vote($feature, $scopeIdentifier = null)
    {
        if ($this->stateChecker($feature, $scopeIdentifier) === StateChecker::VALID_STATE) {
            return self::FEATURE_ENABLED;
        }
        if ($this->stateChecker($feature, $scopeIdentifier) === StateChecker::INVALID_STATE) {
            return self::FEATURE_DISABLED;
        }

        return self::FEATURE_ABSTAIN;
    }
}

Now, configure a voter:

services:
    acme_process.voter.feature_voter:
        class: Acme\Bundle\ProcessorBundle\Voter\FeatureVoter
        arguments: [ '@acme_process.voter.state_checker' ]
        tags:
            - { name: oro_featuretogle.voter }

Change Decision Strategy

There are three strategies available:

  • affirmative – The strategy grants access if one voter grants access;

  • consensus – The strategy grants access if there are more voters that grant access than those that deny;

  • unanimous (default) – The strategy grants access only if all voters grant access.

Strategy configuration (may be defined in Resources/config/oro/app.yml)

oro_featuretoggle:
    strategy: affirmative
    allow_if_all_abstain: true
    allow_if_equal_granted_denied: false

or in feature definition

features:
    acme:
        label: acme.feature.label
        strategy: affirmative
        allow_if_all_abstain: true
        allow_if_equal_granted_denied: false

Use Checker for Commands

Commands launched as subcommands cannot be skipped globally. To avoid running such commands, add an implementation of FeatureCheckerAwareInterface to your parent command, import FeatureCheckerHolderTrait (via use FeatureCheckerHolderTrait;), and check the feature status via featureChecker that is automatically injected into your command.

namespace Acme\Bundle\FixtureBundle\Command;

use Oro\Bundle\FeatureToggleBundle\Checker\FeatureCheckerHolderTrait;
use Oro\Bundle\FeatureToggleBundle\Checker\FeatureCheckerAwareInterface;

class LoadDataFixturesCommand implements FeatureCheckerAwareInterface
{

    use FeatureCheckerHolderTrait;

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $commands = [
            'oro:cron:analytic:calculate' => [],
            'oro:b2b:lifetime:recalculate'          => ['--force' => true]
        ];

        foreach ($commands as $commandName => $options) {
            if ($this->featureChecker->isResourceEnabled($commandName, 'commands')) {
                $command = $this->getApplication()->find($commandName);
                $input = new ArrayInput(array_merge(['command' => $commandName], $options));
                $command->run($input, $output);
            }
        }
    }
}