Getting started¶

Note

It may be helpful to review Drupal's documentation on these topics:

Adding a configuration requirement to a route¶

Define configuration schema¶

Define a boolean configuration value in your module's configuration schema:

config/schema/my_module.schema.yml

my_module.settings:
  type: 'config_object'
  label: 'My module settings'
  mapping:
    enable_my_route:
      type: 'boolean'
      label: 'Enable my route'

Non-boolean configuration values

It's recommended to use configuration values that are boolean type. Technically, any configuration value can be used, but the value will be converted to a boolean when the system is deciding if a route should be enabled.

Create a controller class¶

Add a simple controller:

src/Controller/MyRouteController.php

<?php

declare(strict_types=1);

namespace Drupal\my_module\Controller;

use Drupal\Core\Controller\ControllerBase;

/**
 * Controller.
 */
class MyRouteController extends ControllerBase {

  /**
   * Returns a simple page.
   */
  public function getPage(): array {
    return ['#markup' => $this->t('Page contents')];
  }

}

Define a route for the controller¶

Define a route and add the _config key to the requirements:

my_module.routing.yml

my_module.my_route:
  path: '/my-module/my-route'
  defaults:
    _controller: '\Drupal\my_module\Controller\MyRouteController::getPage'
  requirements:
    _permission: 'administer my module'
    _config: 'my_module.settings.enable_my_route'

Set the configuration value¶

You can use Drush to easily set the configuration value:

# Set my_module.settings.enable_my_route to TRUE to enable the route:
drush config:set my_module.settings enable_my_route 1
# Set my_module.settings.enable_my_route to FALSE to disable the route:
drush config:set my_module.settings enable_my_route 0

If my_module.settings.enable_my_route is TRUE, the route will be enabled. If it is FALSE, the route will not be enabled.

Adding multiple configuration requirements to a route¶

Note

Using multiple configuration requirements works similarly to using multiple permissions in _permission or multiple module dependencies in _module_dependencies, both of which are provided by Drupal core.

You can specify multiple configuration values separated by + for AND logic and , for OR logic.

my_module.routing.yml

my_module.my_route:
  path: '/my-module/my-route'
  defaults:
    _controller: '\Drupal\my_module\Controller\MyRouteController::get'
  requirements:
    _permission: 'administer my module'
    _config: 'my_module.settings.enable_my_route_1+my_module.settings.enable_my_route_2,my_module.settings.enable_my_route_3'

AND logic (+) takes precedence over OR logic (,). In other words, the configuration requirement:

my_module.settings.enable_my_route_1+my_module.settings.enable_my_route_2,my_module.settings.enable_my_route_3

Would be evaluated as:

my_module.settings.enable_my_route_1 AND (my_module.settings.enable_my_route_2 OR my_module.settings.enable_my_route_3)

Which could also be written as:

All of these requirements must be met to enable the route:

my_module.settings.enable_my_route_1 must evaluate to TRUE

At least one of these must evaluate to TRUE:

my_module.settings.enable_my_route_2

my_module.settings.enable_my_route_3

Nested configuration values¶

Nested configuration values are supported.

Define a nested configuration value in your module's configuration schema:

config/schema/my_module.schema.yml

my_module.settings:
  type: 'config_object'
  label: 'My module settings'
  mapping:
    enable_my_route:
      type: 'boolean'
      label: 'Enable my route'
    nested_settings:
      type: 'config_object'
      label: 'Nested settings'
      mapping:
        enabled_my_route_nested:
          type: 'boolean'
          label: 'Enable my route (nested)'

Set the nested configuration value as a requirement on a route:

my_module.routing.yml

my_module.my_route:
  path: '/my-module/my-route'
  defaults:
    _controller: '\Drupal\my_module\Controller\MyRouteController::get'
  requirements:
    _permission: 'administer my module'
    _config: 'my_module.settings.nested_settings.enabled_my_route_nested'