Important

You are browsing upcoming documentation for version 6.0 of OroCommerce, OroCRM, and OroPlatform, scheduled for release in 2024. 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 feature depends on. The feature is enabled when all the features from this list are also enabled.

  • routes - A list of route names.

  • configuration - A list of system configuration group and field names.

  • 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.

  • frontend_api_resources - A list of entity FQCNs that are available as the storefront API resources.

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

  • entities - A list of entity FQCNs.

  • dashboard_widgets - A list of dashboard widget names.

  • sidebar_widgets - A list of sidebar widget names.

  • cron_jobs - A list of CRON commands that depend on the feature. These commands are not executed by the cron when the feature is disabled.

  • navigation_items - A list of navigation item names.

  • placeholder_items - A list of placeholder item names.

  • mq_topics - A list of message queue topic names.

An 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:
            # bind whole API resource / bind all API actions for API resource
            - Acme\Bundle\DemoBundle\Entity\Page
            # bind only specific API actions for API resource
            - [Acme\Bundle\DemoBundle\Entity\Page, [create, update, delete, delete_list]]
        frontend_api_resources:
            # bind whole API resource / bind all API actions for API resource
            - Acme\Bundle\DemoBundle\Entity\Page
            # bind only specific API actions for API resource
            - [Acme\Bundle\DemoBundle\Entity\Page, [create, update, delete, delete_list]]
        commands:
            - oro:search:index
        entities:
            - Acme\Bundle\DemoBundle\Entity\Page
        dashboard_widgets:
            - page_dashboard_widget
        sidebar_widgets:
            - acme_sidebar_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

Note

The oro:feature-toggle:config:dump-reference command can be used to dump the reference structure for Resources/config/oro/features.yml:

php bin/console oro:feature-toggle:config:dump-reference

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\DemoBundle\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\DemoBundle\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, etc.), 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\DemoBundle\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_demo.form.extension.product_form:
        class: Acme\Bundle\DemoBundle\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\DemoBundle\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_demo.voter.feature_voter:
        class: Acme\Bundle\DemoBundle\Voter\FeatureVoter
        arguments: [ '@acme_demo.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\DemoBundle\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);
            }
        }
    }
}