DEV Community: Lusso Luca

Drupal service container deep dive (Part 2): aliases, autowiring, and named arguments

Lusso Luca — Wed, 10 Dec 2025 09:00:00 +0000

In this second part of our deep dive into the Drupal service container, we explore the concepts of aliases, autowiring, and named arguments.

In the first part of this series, we explored the basics of the Drupal service container, including how services are defined and how dependencies are injected. We discussed concepts such as tags, compiler passes, service providers, and autoconfiguration. In this second part, we will delve deeper into more advanced concepts such as aliases, autowiring, and named arguments.

Aliases

An alias in the Drupal service container is a way to create an alternative name for an existing service. This is particularly useful when you want to refer to a service by a different name without changing the original service definition.

request_stack:
  class: Symfony\Component\HttpFoundation\RequestStack
  tags:
    - { name: persist }
Symfony\Component\HttpFoundation\RequestStack: '@request_stack'

In this example, we define a service request_stack and then create an alias Symfony\Component\HttpFoundation\RequestStack that points to the same service. This allows us to refer to the RequestStack service using either name interchangeably. This specific example works because a service name is just a string, and we can use anything that is a valid string as a service name, including class names.

A service name is just a string: config.factory, entity_type.manager, Symfony\Component\HttpFoundation\RequestStack, are all valid service names.

Starting from Drupal 10.1, most of the core services have been aliased with the Fully Qualified Class Name (FQCN) of the service class.

Change record: https://www.drupal.org/node/3323122

Of course, you can create your own aliases in your custom modules to improve code readability and maintainability:

webprofiler.profiler:
 class: Drupal\webprofiler\Profiler\Profiler
 arguments:
   [
     '@webprofiler.file_storage',
     '@logger.channel.webprofiler',
     '@config.factory',
   ]
Drupal\webprofiler\Profiler\Profiler': '@webprofiler.profiler'

When a service name is equal to the service class FQCN, the service container can automatically resolve and inject dependencies simply by matching the requested FQCN.

This feature is called autowiring.

Autowiring

Autowiring is a feature of the Drupal (and Symfony) service container that allows for automatic dependency injection based on type hints. When a service is defined with autowiring enabled, the container will automatically resolve and inject the required dependencies based on the type hints specified in the constructor or method signatures.

The service will be instantiated in exactly the same way as before, but there is no need to explicitly specify which arguments are required; the interfaces/classes that are declared in the service constructor will be used to discover which services should be injected.

Autowire can be enabled at service level, like this:

services:
  _defaults:
    autoconfigure: true

  webprofiler.profiler_listener:
    class: Drupal\webprofiler\EventListener\ProfilerListener
    autowire: true

or globally for all services, like this:

services:
  _defaults:
    autoconfigure: true
    autowire: true

  webprofiler.profiler_listener:
    class: Drupal\webprofiler\EventListener\ProfilerListener

In Symfony, when a single service exists for a given interface or class, the service container automatically creates an alias for it using the FQCN. This means that you can type-hint against the interface or class in your constructor, and the container will automatically inject the correct service. This is not the case in Drupal, where you need to explicitly create the alias as shown above.

Multiple services for the same interface

Usually, a Drupal module extends the logger.channel_base service to build a new logger with the module name, like in this example:

services:
  _defaults:
    autowire: true
    autoconfigure: true

  logger.channel.module_name:
    parent: logger.channel_base
    arguments: ['module_name']

  my_service:
    class: Drupal\module_name\MyService

Both logger.channel_base, logger.channel.module_name, and every logger defined by Core and modules are instances of the same interface: Psr\Log\LoggerInterface. As there are many services in the service container that implement Psr\Log\LoggerInterface, which specific implementation will be injected in a constructor like this?

use Psr\Log\LoggerInterface;

class MyService {

    public function __construct(
      private readonly LoggerInterface $logger,
    ) {
    }
}

In this case, the service container will throw an exception because it cannot determine which specific service to inject:

Some services cannot be autowired, usually because the interface is implemented by multiple different services (like loggers or cache bins in Drupal).
In this case, we must use the #[Autowire] attribute to clearly specify which service to inject, like this:

use Psr\Log\LoggerInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

class MyService {

    public function __construct(
      #[Autowire(service: 'logger.channel.module_name')]
      private readonly LoggerInterface $logger,
    ) {
    }
}

Autowiring in Controllers and Hooks

A controller is not a service and it's not loaded by the service container. When a route is matched, Drupal uses the controller loader service (controller_resolver) to create an instance of the controller class. The controller loader calls the create method on the controller class to instantiate it. The create method receives the entire service container and creates a new instance of the controller class with the required services. This is an implementation of the service locator anti-pattern, as shown in:

class DashboardController extends ControllerBase {

  final public function __construct(
    private readonly Profiler $profiler,
    private readonly TemplateManager $templateManager,
  ) {
  }

  public static function create(ContainerInterface $container): DashboardController {
    return new static(
      $container->get('webprofiler.profiler'),
      $container->get('webprofiler.template_manager'),
    );
  }
}

Starting from Drupal 10.2, ControllerBase (the base class for controllers in Drupal) uses the AutowireTrait, so if the controller constructor uses type hints and the #[Autowire] attribute where necessary, we can take advantage of autowiring in controllers as well.

AutowireTrait uses reflection to read the constructor parameters and their attributes, so it has a performance impact.

use Drupal\Core\DependencyInjection\AutowireTrait;

class DashboardController extends ControllerBase {

  use AutowireTrait;

  final public function __construct(
    private readonly Profiler $profiler,
    private readonly TemplateManager $templateManager,
  ) {
  }
}

As we can see in the previous example, the create method is no longer required. The AutowireTrait can be used for any classes that implement ContainerInjectionInterface (for some reason, FormBase does not use it yet, but you can easily add it to your custom forms).

With the upcoming Drupal 11.3, a similar feature will be available for plugins too: Add create() factory method with autowired parameters to PluginBase.

Starting from Drupal 11.1, hooks can be defined in classes (https://www.drupal.org/node/3442349). All hook classes are automatically registered as autowired services, so you can use autowiring in hook classes as well:

namespace Drupal\file\Hook;

class FileViewsHooks {

  public function __construct(
    protected readonly EntityTypeManagerInterface $entityTypeManager,
    protected readonly EntityFieldManagerInterface $entityFieldManager,
    protected readonly ?FieldViewsDataProvider $fieldViewsDataProvider,
  ) {}

  #[Hook('field_views_data')]
  public function fieldViewsData(FieldStorageConfigInterface $field_storage): array {
    $data = $this->fieldViewsDataProvider->defaultFieldImplementation($field_storage);
  }
}

Autowiring in Services vs Non-Services

It's important to note that while services benefit from autowiring when properly configured, there are cases where you might want to use autowiring but cannot modify the class constructor to fix the type hint or to add the #[Autowire] attribute. This is where named arguments come into play.

Named Arguments

Named arguments provide an alternative way to specify dependencies in the service definition file itself, without requiring changes to the PHP code. This is particularly useful when:

You're working with third-party classes that you cannot modify
You want to keep dependency configuration separate from the code
You need to inject a specific service when multiple implementations of the same interface exist (as an alternative to using the #[Autowire] attribute)

Named arguments allow us to specify which arguments to pass to a service when it is being instantiated, by name rather than by position. The syntax uses the parameter name (with a $ prefix) as the key in the arguments section.

For example, let's say we have a service class with a constructor like this:

namespace Symfony\Component\Messenger\Middleware;

class SendMessageMiddleware {

    public function __construct(
        SendersLocatorInterface $sendersLocator,
        EventDispatcherInterface $eventDispatcher = null,
    ) {
    }
}

Instead of passing arguments by position, we can use named arguments in the service definition:

messenger.middleware.send_message:
  class: Symfony\Component\Messenger\Middleware\SendMessageMiddleware
  arguments:
    $eventDispatcher: '@event_dispatcher'

In this example, we're explicitly specifying that the $eventDispatcher parameter should receive the @event_dispatcher service. This is much clearer than using positional arguments, especially when dealing with optional parameters or when you want to skip some arguments.

Named arguments are particularly powerful when combined with autowiring. The container will:

First try to autowire all type-hinted parameters based on their types
Then override specific parameters with any named arguments you've defined
Use default values for any remaining optional parameters

This means you can let autowiring handle most dependencies automatically while using named arguments only for the specific cases where you need explicit control, such as when multiple services implement the same interface:

services:
  _defaults:
    autowire: true
    autoconfigure: true

  my_custom_service:
    class: Drupal\my_module\MyCustomService
    arguments:
      $logger: '@logger.channel.my_module'

In this example, most dependencies of MyCustomService will be autowired, but we're explicitly specifying which logger to inject using a named argument, solving the ambiguity problem we discussed earlier.

Bringing It All Together

Now that we understand aliases, autowiring, and named arguments, let's see how they work together to simplify service definitions.

Traditional Service Definition

In older Drupal code, a service definition might look like this:

services:
  webprofiler.profiler_listener:
    class: Drupal\webprofiler\EventListener\ProfilerListener
    arguments:
      - '@webprofiler.profiler'
      - '@request_stack'
      - '@webprofiler.matcher.exclude_path'

This approach requires:

Explicitly listing every dependency
Maintaining the correct order of arguments
Updating the YAML file whenever constructor parameters change

Modern Service Definition with Aliases and Autowiring

With the concepts we've covered, we can dramatically simplify this:

services:
  _defaults:
    autoconfigure: true
    autowire: true

  Drupal\webprofiler\EventListener\ProfilerListener: ~

This works because:

Aliases: The service is registered using its FQCN, which serves as both the service name and alias
Autowiring: The container automatically resolves dependencies based on type hints in the constructor
Autoconfiguration: The service is automatically tagged if it implements certain interfaces

In Yaml, ~ symbol (tilde) is equivalent to an empty array or null, meaning no additional configuration is needed. In this case, the tilde can be omitted entirely, but in my opinion, it's clearer to explicitly show that no further configuration is necessary.

Conclusion

In this second part of our deep dive into the Drupal service container, we have explored three powerful concepts that work together to modernize dependency injection in Drupal:

Aliases enable us to reference services by their class names, making code more intuitive and refactoring safer
Autowiring eliminates boilerplate by automatically resolving dependencies based on type hints
Named arguments provide surgical precision when we need explicit control over specific dependencies

Together, these features reduce boilerplate code, improve maintainability, and make service definitions more readable. They represent a significant evolution in how Drupal developers work with the service container.

Stay tuned for the next parts of this series, where we will continue to explore more advanced features of the Drupal service container:

Part 1 covers service tags, compiler passes, service providers, and autoconfiguration, laying the groundwork for understanding how services are defined and managed within the container.
Part 3 will cover service collectors, which aggregate multiple services into a single service for streamlined access.
Part 4 will explore factories, which provide a mechanism for creating services with complex initialization logic.
Part 5 will discuss backend overrides, enabling developers to customize service implementations for specific environments or use cases.
Part 6 will examine advanced features of the Drupal service container, such as service decoration and lazy loading.

Drupal service container deep dive part 1: tags, compiler passes, service providers and autoconfiguration

Lusso Luca — Mon, 03 Nov 2025 09:00:00 +0000

In this first part of our deep dive into the Drupal service container, we explore the concepts of tags, compiler passes, service providers, and autoconfiguration.

The evolution of Drupal core has increasingly embraced modern PHP standards and robust object-oriented programming (OOP) principles, driven largely by its integration of Symfony components. Central to this modernization is the Service Container, which acts as the core registry responsible for service instantiation, dependency resolution, and lifecycle management.

A service is inherently a specialized, reusable, and stateless object designed to perform a single, well-defined task, such as ConfigFactory for configuration access or EntityTypeManager for entity access.

The philosophy underpinning service usage is the promotion of loose coupling and adherence to the Dependency Inversion Principle (DIP). A class using a service should request it from the container rather than manually instantiating it with the new keyword. This arrangement enables developers to swap implementations without altering consuming code.

In this series of articles, we will explore the Drupal service container in depth, focusing on its features, capabilities, and best practices for leveraging it effectively in Drupal module development.

Part 1 will cover service tags, compiler passes, service providers, and autoconfiguration, laying the groundwork for understanding how services are defined and managed within the container.
Part 2 will delve into aliases, autowiring, and name arguments, demonstrating how to resolve and inject dependencies based on type hints, reducing boilerplate code and enhancing maintainability.
Part 3 will cover service collectors, which aggregate multiple services into a single service for streamlined access.
Part 4 will explore factories, which provide a mechanism for creating services with complex initialization logic.
Part 5 will discuss backend overrides, enabling developers to customize service implementations for specific environments or use cases.
Part 6 will examine advanced features of the Drupal service container, such as service decoration and lazy loading.

Anatomy of a Drupal service

A Drupal service is defined within a module's MODULE.services.yml file:

# in modules/contrib/webprofiler/webprofiler.services.yml
services:
    webprofiler.matcher.exclude_path:
        class: Drupal\webprofiler\RequestMatcher\WebprofilerRequestMatcher
        arguments: ['@path.matcher', '@config.factory', 'exclude_paths']

# in core/core.services.yml
services:
    path.matcher:
        class: Drupal\Core\Path\PathMatcher
        arguments: ['@config.factory', '@current_route_match']
    config.factory:
        class: Drupal\Core\Config\ConfigFactory
    current_route_match:
        class: Drupal\Core\Routing\CurrentRouteMatch
        arguments: ['@request_stack']
    request_stack:
        class: Symfony\Component\HttpFoundation\RequestStack

When code asks for the webprofiler.matcher.exclude_path service, the Drupal service container first builds all the required services and finally builds an instance of the WebprofilerRequestMatcher class by injecting all the dependencies in the __construct method:

namespace Drupal\webprofiler\RequestMatcher;

use Drupal\Core\Config\ConfigFactoryInterface;
use Drupal\Core\Path\PathMatcherInterface;
use Symfony\Component\HttpFoundation\RequestMatcherInterface;

class WebprofilerRequestMatcher implements RequestMatcherInterface {

  public function __construct(
    private readonly PathMatcherInterface $pathMatcher,
    private readonly ConfigFactoryInterface $configFactory,
    private readonly string $configuration,
  ) {...}
}

The resolution graph looks like this:

So Drupal first builds the request_stack service, then the current_route_match service (which depends on request_stack), then the config.factory service, then the path.matcher service (which depends on both config.factory and current_route_match), and finally the webprofiler.matcher.exclude_path service (which depends on both path.matcher and config.factory).

Notice that the third argument of the webprofiler.matcher.exclude_path service is a string (exclude_paths). The service container supports injecting scalar values like strings, integers, and booleans as arguments to services:

@ prefix indicates a service reference.
% prefix indicates a parameter reference.
@? indicates an optional service reference.
No prefix indicates a literal value.

parameters:
  param1: 'some string'

services:
  some_service1:
    class: Some\Class\Name1

  some_service2:
    class: Some\Class\Name2
    arguments: ['@some_service1', '%param1%', 42, true, 'another string', '@?some_service3']

and the code for some_service2 would look like this:

namespace Some\Class;

class Name2 {
  public function __construct(
    private readonly Name1 $someService1,
    private readonly string $param1,
    private readonly int $param2,
    private readonly bool $param3,
    private readonly string $param4,
    private readonly ?Name3 $someService3 = null,
  ) {...}
}

Differences between Drupal and Symfony service containers

The Drupal service container is built on top of the Symfony service container, inheriting many of its features and capabilities. However the Drupal modular architecture and specific requirements have led to several changes. On the other hand, Drupal doesn't use the Symfony Config component for service configuration, instead relying on its own YAML-based service definition files.

At the end both YAML loading and service container dumping have been heavily customized in Drupal to fit its architecture and performance needs, resulting in a service container that is optimized for Drupal's unique use cases but not fully equivalent to the standard Symfony service container.

Those differences can lead to some confusion when reading Symfony documentation, as some features may not be available or behave differently in Drupal. This article series aims to clarify those differences and provide a comprehensive understanding of the Drupal service container.

Service Tags

Service tags are metadata annotations that can be applied to service definitions within the Drupal service container. They provide a way to categorize and group services based on their functionality or purpose.

services:
  webprofiler.database:
    class: Drupal\webprofiler\DataCollector\DatabaseDataCollector
    arguments: ['@database', '@config.factory']
    tags:
      - {
          name: data_collector,
          template: '@webprofiler/Collector/database.html.twig',
          id: 'database',
          label: 'Database',
          priority: 750,
        }

A tag has a mandatory name attribute and can have any number of additional attributes. In the example above, the webprofiler.database service is tagged with the data_collector tag, along with several additional attributes such as template, id, label, and priority.

Tags on their own don't actually alter the functionality of a service in any way. They are primarily used to identify services for special processing during the container compilation phase, often through the use of compiler passes.

Compiler Passes

Compiler passes are a mechanism that allows developers to modify the service container during its compilation phase. They provide a way to programmatically alter service definitions, add or remove services, and manipulate tags before the container is fully built and dumped to the cache

Compiler passes are particularly useful for implementing complex service registration logic, such as dynamically adding services based on configuration or other runtime conditions. They are executed in a specific order during the container compilation process, allowing for fine-grained control over the final service definitions.

namespace Drupal\webprofiler\Compiler;

use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;

final class ProfilerPass implements CompilerPassInterface {

  public function process(ContainerBuilder $c): void {

    foreach ($c->findTaggedServiceIds('data_collector', TRUE) as $id => $attributes) {
        ...
    }
  }
}

A shown in the example above, the ProfilerPass class implements the CompilerPassInterface and defines a process method that is called during the container compilation phase. Within this method, the findTaggedServiceIds function is used to retrieve all services tagged with data_collector, allowing for custom processing of those services. The process method can modify the service definitions as needed, such as adding additional arguments, changing class names, or even removing services from the container.

A compiler pass must be registered with the container in order to be executed during the compilation phase. This is typically done within a module's service provider class.

Service Providers

Service providers are classes that encapsulate the logic for dynamically registering or altering services within the Drupal service container. Service providers typically extend the ServiceProviderBase class and re-define the register or alter methods to add or modify service definitions.

namespace Drupal\webprofiler;

use Drupal\Core\DependencyInjection\ContainerBuilder;
use Drupal\Core\DependencyInjection\ServiceProviderBase;

class WebprofilerServiceProvider extends ServiceProviderBase {

  public function register(ContainerBuilder $container): void {
    [...]
  }

  public function alter(ContainerBuilder $container): void {
     [...]
  }
}

The name and the namespace of the service provider class must follow a specific convention: it should be named ModuleServiceProvider and be located in the root namespace of the module. For example, the service provider for the webprofiler module is named WebprofilerServiceProvider and is located in the Drupal\webprofiler namespace. If the module name contains underscores, they should be removed and the following letter capitalized (e.g., search_api becomes SearchApiServiceProvider). Core has its own service provider named CoreServiceProvider located in the Drupal\Core namespace.

The register method can be used to add compiler passes to the container:

namespace Drupal\webprofiler;

use Drupal\Core\DependencyInjection\ContainerBuilder;
use Drupal\Core\DependencyInjection\ServiceProviderBase;

class WebprofilerServiceProvider extends ServiceProviderBase {

  public function register(ContainerBuilder $container): void {
    $container->addCompilerPass(new ProfilerPass());
  }
}

If the order of execution of compiler passes matters, you can specify the pass type and priority when adding the compiler pass:

$container->addCompilerPass(
  pass: new ProfilerPass(),
  type: PassConfig::TYPE_BEFORE_OPTIMIZATION,
  priority: 10
);

Values for type can be:

PassConfig::TYPE_BEFORE_OPTIMIZATION
PassConfig::TYPE_OPTIMIZE
PassConfig::TYPE_BEFORE_REMOVING
PassConfig::TYPE_REMOVE
PassConfig::TYPE_AFTER_REMOVING

This diagram that illustrates when compiler passes are executed during the Symfony service container compilation process:

TYPE_BEFORE_OPTIMIZATION (Blue): Where most custom compiler passes (like ProfilerPass) are typically registered. This is where services are analyzed and tagged services are processed.

TYPE_OPTIMIZE (Purple): Internal Symfony optimization passes that inline services and optimize the container structure.

TYPE_BEFORE_REMOVING (Orange): Validation passes that check for circular references and definition validity before cleanup.

TYPE_REMOVE (Red): Cleanup passes that remove unused services and private aliases.

TYPE_AFTER_REMOVING (Green): Final optimization passes after cleanup is complete.

Within each phase, compiler passes are executed in priority order (highest to lowest), allowing for fine-grained control over the execution sequence when multiple passes are registered in the same phase.

Autoconfiguration

Autoconfiguration is a powerful feature of the Drupal service container that allows services to be automatically tagged based on their class definitions.

When a service is defined in the container, the autoconfiguration process analyzes the class and applies the appropriate tags. For example, if a service implements a specific interface or extends a particular base class, the container can automatically apply the relevant tags to the service definition.

namespace Drupal\Core;

class CoreServiceProvider
    implements ServiceProviderInterface, ServiceModifierInterface {

    public function register(ContainerBuilder $container) {
        [...]
        $container
          ->registerForAutoconfiguration(EventSubscriberInterface::class)
          ->addTag('event_subscriber');
    }

    public function alter(ContainerBuilder $container): void {
        [...]
    }
}

In the example above, the CoreServiceProvider class registers an autoconfiguration rule that automatically tags any service implementing the EventSubscriberInterface with the event_subscriber tag. This means that when a service is defined that implements this interface, it will automatically receive the event_subscriber tag without needing to explicitly define it in the service definition.

Autoconfiguration is particularly useful for module developers, as it streamlines the process of registering services and ensures that they are properly configured without requiring extensive boilerplate code.

Since Drupal 10.2.0, several interfaces have been registered for autoconfiguration in CoreServiceProvider. At the time of writing (Drupal 11.3.0), those interfaces, and their corresponding tags, are:

MediaLibraryOpenerInterface (tag: media_library.opener)
EventSubscriberInterface (tag: event_subscriber)
LoggerAwareInterface (tag: logger_aware)
PreWarmableInterface (tag: cache_prewarmable)
ModuleUninstallValidatorInterface (tag: module_install.uninstall_validator)

Of course, custom autoconfiguration rules can be added in any module's service provider class, allowing for tailored service tagging based on specific module requirements:

namespace Drupal\sm;

final class SmServiceProvider implements ServiceProviderInterface {

  public function register(ContainerBuilder $container): void {
    $container->registerForAutoconfiguration(TransportFactoryInterface::class)
      ->addTag('messenger.transport_factory');
    $container->registerForAutoconfiguration(ServiceLocator::class)
      ->addTag('container.service_locator');
    }
}

Unfortunately, autoconfiguration only works for tags that doesn't have attributes.

With all those concepts in place, we can remove some boilerplate from our service definition by going from a service definition like this:

webprofiler.profiler_listener:
  class: Drupal\webprofiler\EventListener\ProfilerListener
  arguments:
    - '@webprofiler.profiler'
    - '@request_stack'
    - '@webprofiler.matcher.exclude_path'
  tags:
    - { name: event_subscriber }

to this:

webprofiler.profiler_listener:
  class: Drupal\webprofiler\EventListener\ProfilerListener
  arguments:
    - '@webprofiler.profiler'
    - '@request_stack'
    - '@webprofiler.matcher.exclude_path'

assuming that the ProfilerListener class implements the EventSubscriberInterface, which is already registered for autoconfiguration in CoreServiceProvider.

In the next part of this series, we will explore aliases, autowiring, and named arguments, demonstrating how to resolve and inject dependencies based on type hints, reducing boilerplate code, enhancing maintainability, and going even further in simplifying service definitions by removing the arguments section entirely:

webprofiler.profiler_listener:
  class: Drupal\webprofiler\EventListener\ProfilerListener

Stay tuned!

Drupal Access Policy demystified

Lusso Luca — Mon, 24 Jun 2024 10:35:53 +0000

Access Policy in Core

Drupal 10.3 introduces a new way to assign permissions to users, going beyond the traditional roles and permissions system. This new system is called the Access Policy API, and in this blog post, we'll try to explain how it works and how to use it.

The old way

Until Drupal 10.2, the access control system was based on two main concepts: you were either in a role that granted you a set of permissions or the user with UID 1, and the access checks were bypassed.

For example, you can have this code somewhere:

public function access(AccountInterface $account) {
   return $account->hasPermission('access content');
}

The code for hasPermission simply checks for the two cases mentioned above: if the user is the one with UID 1 or if the user is in a role that grants that permission:

public function hasPermission(string $permission, AccountInterface $account): bool {
   // User #1 has all privileges.
   if ((int) $account->id() === 1) {
      return TRUE;
   }

   return $this->entityTypeManager
      ->getStorage('user_role')
      ->isPermissionInRoles($permission, $account->getRoles());
}

This implementation was quite simple and worked well when a user has a set of permissions that are valid sitewide and that don't change based on some external factors.

If you need to implement use cases like:

deny edit permissions on weekends
allow edit permissions only if the user has 2FA enabled
allow edit permissions only to contents in a group (or in a domain, or in a Commerce store, etc.)

You're probably going to need a lot of custom code (otherwise it's impossible to implement them).

The new way

Drupal 10.3 introduced a new Access Policy API that allows the definition of a set of policies that can be applied based on a context.

If you want to know something about the genesis of this new system, you can read this blog post: Policy-Based Access in Core by Kristiaan Van den Eynde.

The API is quite simple; you define a policy class that extends the \Drupal\Core\Session\AccessPolicyBase and provide, at least, the implementation for the methods:

calculatePermissions(AccountInterface $account, string $scope): RefinableCalculatedPermissionsInterface: Calculates the permissions for an account within a given scope
getPersistentCacheContexts(): array: Gets the initial cache context this policy varies by

A policy is then registered in the service container with the tag access_policy.

Drupal 10.3 mimics the old behavior by providing two default policies:

\Drupal\Core\Session\Access\UserRolesAccessPolicy: Grants permissions based on a user's roles
\Drupal\Core\Session\Access\SuperUserAccessPolicy: Bypass permissions checks for the user with UID equal to 1

The \Drupal\Core\Session\Access\UserRolesAccessPolicy, for example, is implemented as follows:

final class UserRolesAccessPolicy extends AccessPolicyBase {

   public function __construct(protected EntityTypeManagerInterface $entityTypeManager) {}

   public function calculatePermissions(AccountInterface $account, string $scope): RefinableCalculatedPermissionsInterface {
      $calculated_permissions = parent::calculatePermissions($account, $scope);
      $user_roles = $this->entityTypeManager->getStorage('user_role')->loadMultiple($account->getRoles());

      foreach ($user_roles as $user_role) {
         $calculated_permissions
            ->addItem(new CalculatedPermissionsItem($user_role->getPermissions(), $user_role->isAdmin()))
            ->addCacheableDependency($user_role);
      }

      return $calculated_permissions;
   }

   public function getPersistentCacheContexts(): array {
      return ['user.roles'];
   }
}

The previous code retrieves the user's roles and adds a CalculatedPermissionsItem with the permissions granted by each role. Then, it adds a cacheable dependency on the role entity so that if the role's permissions change, the cache is invalidated. Finally, the method getPersistentCacheContexts returns the initial cache context that the policy varies by.

We will discuss the meaning of (Refinable)CalculatedPermissions, scope, and initial cache context shortly.

The critical thing to understand here is that this new system does not aim to grant access to something, like editing a node or viewing a page. It's designed to calculate a user's permissions in a given context. The access check is still done in the old way, which checks if the user has specific permission to perform a task.

An access policy converts a context into a set of permissions

Access policies are services, allowing us to replace or decorate the implementation provided by Core. Indeed, the Core itself allows for the policy for the super user to be disabled to increase site security (https://www.drupal.org/node/2910500). With the super user policy disabled, we may want to define a new one that grants admin permissions based on other user characteristics. For instance, we can specify that the site admins are users with a specific email domain or who have logged in through a particular authentication system.

Now, let's dive into the details of the new system using some examples.

Example 1 (alter permissions provided by Core)

Let's say we want to add a new policy that grants permission to access promotional banners only if the current language is English.

The LanguageAccessPolicy.php class may look like this:

class LanguageAccessPolicy extends AccessPolicyBase {

   public function alterPermissions(
      AccountInterface $account,
      string $scope,
      RefinableCalculatedPermissionsInterface $calculated_permissions
   ): void {
      if (\Drupal::languageManager()->getCurrentLanguage()->getId() == 'en') {
         $calculated_permissions->addItem(
            item: new CalculatedPermissionsItem(
               permissions: ['access promotional banners'],
               isAdmin: FALSE
            ),
            overwrite: FALSE
         );
      }
   }

   public function getPersistentCacheContexts(): array {
      return ['languages'];
   }
}

To register the policy in the service container, you need to add the following to your access_policy_demo.services.yml:

services:
   access_policy_demo.access_policy.language:
      class: Drupal\access_policy_demo\Access\LanguageAccessPolicy
      tags:
         - { name: access_policy }

You can now have this render array sonewhere in your code:

$build['content'] = [
   '#markup' => $this->currentUser()->hasPermission('access promotional banners') ? 'Some promotional banner' : '',
   '#cache' => [
      'contexts' => ['languages'],
   ],
];

The previous code will show the promotional banner only if the current language is English.

Revoke permission is possible by setting the overwrite parameter of the addItem method to TRUE, like this:

$new_permissions = array_diff(
   $calculated_permissions->getItem()->getPermissions(),
   ['view page revisions']
);

$calculated_permissions->addItem(
   item: new CalculatedPermissionsItem(
      permissions: $new_permissions,
      isAdmin: FALSE
   ),
   overwrite: TRUE
);

Altering permissions is possible because, during the access policy calculation, the object that holds the calculated permissions is an instance of the RefinableCalculatedPermissionsInterface that allows the addition or removal of permissions.
When the build and alter phases are complete, the calculated permissions are converted to an immutable object of type CalculatedPermissionsInterface. Using an immutable object guarantees that the computed permissions are not altered after the access policy calculation.

Drupal has moved from an RBAC (Role-Based Access Control) to a PBAC (Policy-Based Access Control) system where permissions are calculated based on a set of policies that are applied in a given context.

Access policies are tagged services, so you can define the priority with which they are applied:

services:
   access_policy_demo.access_policy.language:
      class: Drupal\access_policy_demo\Access\LanguageAccessPolicy
      tags:
         - { name: access_policy, priority: 100 }

The priority is a positive or negative integer that defaults to 0. The higher the number, the earlier the tagged service will be located in the service collection.

Now it's time to talk about scopes.

Example 2 (split the site into sections)

Until now, we have ignored the scope parameter, but look at how the hasPermission() method is implemented in Drupal 10.3:

public function hasPermission(string $permission, AccountInterface $account): bool {
   $item = $this->processor->processAccessPolicies($account)->getItem();
   return $item && $item->hasPermission($permission);
}

The processAccessPolicies() has a second, non-mandatory parameter: the scope.
The getItem() method has two non-mandatory parameters: the scope and the identifier.

Within Core, both scope and identifier default to AccessPolicyInterface::SCOPE_DRUPAL, and you probably don't have to deal with them in most cases.

But what are they used for?

The scope is a string that identifies the context in which the policy is applied, like a group, a domain, a commerce store, etc. The identifier is a string that identifies the specific value within the scope (like the group ID, the domain ID, etc).

The AccessPolicyInterface defines the applies(string $scope): bool method, which determines whether the policy should be applied in a given scope.

Let's try to implement (a very simplified) version of modules like Permissions by Term or Taxonomy Access Control Lite using the new system.

Suppose we have a vocabulary access, which terms represent a group of content that can be accessed only by a specific set of users. Content types and users are tagged with terms of this vocabulary.
The permissions a user has are calculated based on the standard roles mechanism of Drupal. But on nodes tagged with a term of the access vocabulary, if the user is tagged with the same term, the user has the permissions granted by an additional role.

We have the Content editor role that grants standard permissions like Article: Create new content or View own unpublished content, and the Content editor in term role that grants permissions like Article: Edit any content or Article: Delete any content. An editor always has the permissions granted by the Content editor role. Still, on nodes tagged with a term of the access vocabulary, if the user is tagged with the same term, the user has the permissions granted by the Content editor in term role too.

Image: User roles configuration section

The code for the TermAccessPolicy.php class may look like this:

class TermAccessPolicy extends AccessPolicyBase {
   public const SCOPE_TERM = 'term';

   public function applies(string $scope): bool {
      return $scope === self::SCOPE_TERM;
   }

   public function calculatePermissions(AccountInterface $account, string $scope): RefinableCalculatedPermissionsInterface {
      $calculated_permissions = parent::calculatePermissions($account, $scope);

      if ($scope != self::SCOPE_TERM) {
         return $calculated_permissions;
      }

      $user = User::load($account->id());
      $user_terms = $user->get('field_access')->referencedEntities();
      foreach ($user_terms as $user_term) {
         $cacheability = new CacheableMetadata();
         $cacheability->addCacheableDependency($user_term);

         $calculated_permissions
            ->addItem(
               new CalculatedPermissionsItem(
                  permissions: $permissions,
                  isAdmin: FALSE,
                  scope: self::SCOPE_TERM,
                  identifier: $user_term->id()
               )
            )
            ->addCacheableDependency($cacheability);
      }

      return $calculated_permissions;
   }

   private function getPermissions(AccountInterface $account): array {
      $extra_roles = User::load($account->id())
         ->get('field_extra_role')
         ->referencedEntities();

      if (count($extra_roles) === 0) {
         return [];
      }

      $extra_role = reset($extra_roles);

      return $extra_role->getPermissions();
   }

   public function getPersistentCacheContexts(): array {
      return ['user.terms'];
   }
}

In the previous code, we've defined a new scope term and we've implemented the applies method to return TRUE only if the scope is term.
Then, we calculate the permissions based on the terms the user is tagged with. We add a cacheable dependency on the term entity to invalidate the cache if the term changes.

Note that we've passed two more arguments to the addItem method: the scope and the identifier. The scope is the string term, and the identifier is the term ID.

We can register the policy in the service container with the following code:

access_policy_demo.access_policy.term:
   class: Drupal\access_policy_demo\Access\TermAccessPolicy
   tags:
      - { name: access_policy }

The getPersistentCacheContexts() uses a custom cache context, so we've to define it, too:

class UserTermsCacheContext implements CalculatedCacheContextInterface {
   public function __construct(
      protected readonly AccountInterface $account,
   ) {}

   public static function getLabel(): string {
      return t("User's terms");
   }

   public function getContext($term = NULL): string {
      $user = User::load($this->account->id());
      $user_terms = array_map(
         fn($loaded_term) => $loaded_term->id(),
         $user->get('field_access')->referencedEntities()
      );

      if ($term === NULL) {
         return implode(',', $user_terms);
      } else {
         return (in_array($term, $user_terms) ? 'true' : 'false');
      }
   }

   public function getCacheableMetadata($term = NULL): CacheableMetadata {
      return (new CacheableMetadata())->setCacheTags(['user:' . $this->account->id()]);
   }
}

A cache context needs to be registered in the service container, like:

cache_context.user.terms:
   class: Drupal\access_policy_demo\Access\UserTermsCacheContext
   arguments:
      - '@current_user'
   tags:
      - { name: cache.context }

Finally, we can use the new scope to check the permissions:

function access_policy_demo_node_access(NodeInterface $node, $operation, AccountInterface $account): AccessResultInterface {
   $access = FALSE;

   // This node is not under access control.
   if (!$node->hasField('field_access')) {
      return AccessResult::allowed();
   }

   // Always allow access to view the node.
   if ($operation == 'view') {
      return AccessResult::allowed();
   }

   // Check if the user has access to the node.
   $terms = $node->get('field_access')->referencedEntities();
   $type = $node->bundle();
   foreach ($terms as $term) {
      $item = \Drupal::service('access_policy_processor')
         ->processAccessPolicies($account, TermAccessPolicy::SCOPE_TERM)
         ->getItem(TermAccessPolicy::SCOPE_TERM, $term->id());

      if (!$item) {
         continue;
      }

      switch ($operation) {
         case 'update':
            $access = $item->hasPermission('edit any ' . $type . ' content');
            if (!$access && $item->hasPermission('edit own ' . $type . ' content')) {
               $access = $account->id() == $node->getOwnerId();
            }
            break;

         case 'delete':
            $access = $item->hasPermission('delete any ' . $type . ' content');
            if (!$access && $item->hasPermission('delete own ' . $type . ' content')) {
               $access = $account->id() == $node->getOwnerId();
            }
            break;

         default:
            $access = TRUE;
      }

      if ($access) {
         break;
      }
   }

   return $access ? AccessResult::allowed() : AccessResult::forbidden();
}

The previous code is just a rough example. Still, the critical thing to note is that we've used the TermAccessPolicy::SCOPE_TERM and the term ID to retrieve a CalculatedPermissionsItem that contains the permissions granted by the term to the user.

What a long journey! But we're not done yet.

One of the new system's most important features is that access policies are cached by context, but context can be dynamic and change during permission calculation; this is where the initial cache context comes into play.

Variation cache

Access policies usually vary by some context, like the user roles, the time of day, the domain, etc. Drupal has a concept of cache contexts that allows you to vary the cache based on some context, but until Drupal 10.2, this can be used only to add cache contexts to render arrays.

Now, all caches can use cache contexts thanks to the Variation cache.

Variation cache is not a new type of cache but a wrapper around the cache backends that already exist in Drupal. It has two interesting features.
The first one is that it allows varying a cache by context:

cache.access_policy:
   class: Drupal\Core\Cache\CacheBackendInterface
   tags:
      - { name: cache.bin }
   factory: ['@cache_factory', 'get']
   arguments: [access_policy]

variation_cache.access_policy:
   class: Drupal\Core\Cache\VariationCacheInterface
   factory: ['@variation_cache_factory', 'get']
   arguments: [access_policy]

In the previous example, variation_cache.access_policy is a wrapper around cache.access_policy. When I do something like:

$cache = \Drupal::service('variation_cache.access_policy');
$cache->set(['key1', 'key2'], 'value', ['user.roles', 'languages:language_interface'], ['user.roles']);

I'm saving value at the ['key1', 'key2'] of the access_policy cache, and I'm telling the variation cache that the cache will vary by the user.roles and languages:language_interface contexts.

Having not specified anything specific in the tags section of the cache.access_policy service, I get the default cache backend, typically the database one. I could have written:

tags:
   - { name: cache.bin.memory, default_backend: cache.backend.memory.memory }

To have a cache in memory.

Variation cache uses cache contexts to build cache IDs. For example, the cid for the contexts user.roles and languages:language_interface when the user has roles 3 and 4, and the language is English could be something like: key1:key2:[languages:language_interface]=en:[user.roles]=3,4. (Contexts are sorted in alphabetical order by name.)

The second feature comes from the fact that when I save data in the variation cache, I can specify two sets of contexts: the actual ones to vary the cache on (the third argument of the set method) and the "initial" ones (the fourth argument of the set method).

But what are these initial cache contexts? They are the ones that our data varies for sure, but they could not be the only ones. If, during the building of the data to cache, someone else adds one or more specific contexts, the cache system may not be aware of it.

When the set of final cache contexts is more specific than the initial ones, the variation cache stores a cache with an ID built using the initial cache contexts. That cache will not store the data but a redirect that contains the final cache contexts to use to find the actual data. This chain of redirects can span more than one level.

Let's add more complexity to our previous example about the TermAccessPolicy. Suppose that terms in the access vocabulary have a select field named is_restricted, with two values: Weekend and Weekdays. We want to grant the permissions not only if the node is tagged with a term but also based on the day of the week.

Image: Add a restriction to an access term

If no restrictions are set, the permissions are granted as usual. If a restriction is set, the permissions are only granted if the current day matches the restriction.

foreach ($user_terms as $user_term) {
   $cacheability = new CacheableMetadata();
   $cacheability->addCacheableDependency($user_term);

   $restricted = $this->isRestricted($user_term);
   if ($restricted) {
      $cacheability->addCacheContexts(['is_restricted']);
      $permissions = [];
   } else {
      $permissions = $this->getPermissions($account);
   }

   $calculated_permissions
      ->addItem(
         new CalculatedPermissionsItem(
            permissions: $permissions,
            isAdmin: FALSE,
            scope: self::SCOPE_TERM,
            identifier: $user_term->id()
         )
      )
      ->addCacheableDependency($cacheability);
}

return $calculated_permissions;

The isRestricted method can be implemented as follows:

private function isRestricted(TermInterface $user_term): bool {
   $restriction = $user_term->get('field_restriction')->getValue();

   if (count($restriction) == 0 || count($restriction) == 2) {
      return FALSE;
   }

   $field_value = $restriction[0]['value'];

   if ($field_value === 'weekend' && IsWeekendCacheContext::isWeekend()) {
      return FALSE;
   }

   if ($field_value === 'weekdays' && !IsWeekendCacheContext::isWeekend()) {
      return FALSE;
   }

   return TRUE;
}

The RestrictedCacheContext class can be like this:

class RestrictedCacheContext implements CalculatedCacheContextInterface {
   public static function getLabel(): string {
      return t('Is Weekend?');
   }

   public function getContext($parameter = NULL): string {
      $result = static::isWeekend() ? 'weekend' : 'weekday';

      return "is_restricted.{$result}";
   }

   public static function isWeekend(): bool {
      return date('w', time()) % 6 === 0;
   }

   public function getCacheableMetadata($parameter = NULL): CacheableMetadata {
      return (new CacheableMetadata());
   }
}

Now suppose to have two terms:

Section1 (tid=1) with the restriction set to Weekend
Section2 (tid=2) with no restrictions

And two users:

User1 tagged with Section1
User2 tagged with Section2

And we're on Sunday.

When permissions are calculated for User1, the initial cache context will be user.terms, but then we'll add the is_restricted cache context because the Section1 term is restricted.
When permissions are calculated for User2 the initial cache context will be user.terms, and no other cache context will be added.

The cache will be something like:

access_policies:term:[user.terms]=2 => Drupal\Core\Session\RefinableCalculatedPermissions
access_policies:term:[user.terms]=1 => Drupal\Core\Cache\CacheRedirect (cacheContexts: ["user.terms", "is_restricted"])
access_policies:term:[is_restricted]=is_restricted.weekend:[user.terms]=1 => Drupal\Core\Session\RefinableCalculatedPermissions

The Variation cache stores the data for access policies that vary only by user.terms directly.
For the access policies that also vary by is_restricted, it stores a redirect (along with information about the final cache contexts to look for: user.terms and is_restricted).
To access a cache with more final cache contexts than the initial ones, the variation cache will need to follow a chain of redirects.

Conclusion

The new Access Policy API is a powerful tool that allows the implementation of complex access control systems in Drupal.
It's a big step forward from the old system based on only roles and permissions.

In the future, we'll see more and more contrib modules that will use this new system to convert custom logic to the new system. At SparkFabrik, we've already started using it in custom modules for our customers.

Resources:

I've set up a GitHub repository with the code used in this blog post: https://github.com/lussoluca/access_policy_demo. You can clone it and use DDEV to run the code.

This blog post would not have been possible without the help of the following resources:

Drupal new contributions releases

Lusso Luca — Tue, 21 Nov 2023 09:00:00 +0000

A list of new releases and fixes on Drupal modules maintained in SparkFabrik.

Release day

On November 8 2023, I updated a couple of modules that I maintain. No significant changes, just some bug fixes and improvements.

The biggest change is that I've switched to GitlabCI for continuous integration. Now, all the modules are tested with phpcs, PHPStan, Stylelint, Eslint, and PHPUnit.
The integration with the new CI system provided by the Drupal Association is pretty simple to use; just follow the documentation: https://www.drupal.org/node/3356364.
I've made some changes to the standard template to be sure that the pipelines fail in case of errors (take a look at the .gitlab-ci.yml file in the WebProfiler module: https://git.drupalcode.org/project/webprofiler/-/blob/10.1.x/.gitlab-ci.yml).
The provided template looks for configuration files for phpcs and PHPStan, and you can see how I've configured them here: https://git.drupalcode.org/project/webprofiler/-/blob/10.1.x/phpstan.neon and here: https://git.drupalcode.org/project/webprofiler/-/blob/10.1.x/phpcs.xml.dist.

PHPStan is set to level 5, not the maximum level, but it's a good start. I've also added a set of rules to the phpcs configuration file that comes from the previousnext/coding-standard package.

Now, let's see what's new in the modules.

WebProfiler 10.1.3

In the new Drupal 10.1, the Database API can trigger events on the execution of statements. Previously, the module was using the logging capabilities of the Database API to collect the queries, and now it uses the new events. This new system can be used to analyze better the database layer of Drupal.

The routing data collector now shows more information about the page title and the controller that will be used to render the page.

Tracer 1.0.1

A couple of bug fixes have been made to the module behind the WebProfiler module.

At the moment, Tracer is not actively used by any other module, but its future is bright. I'm planning to start working again on the Observability suite module (https://www.drupal.org/project/o11y), and Tracer is the tool that will be used to collect the data.

Monolog 3.0.1

Again, there are no big changes here, but a simple new feature that can improve the analysis of the logs produced by Drupal.

Due to some internal implementation, the batch operations invoked by Drush don't work if the line formatter set in Monolog produces a JSON string.
Having the logs in JSON format is useful to analyze them with tools provided by all the major cloud providers. Until now, if you have to run some Drush commands that internally use batch operations, you have to switch to the drush formatter. The latest version of the Monolog module adds a new conditional formatter that can be used to choose which formatter to use based on some condition. For example, if you want to use the JSON formatter for all the logs except for the ones produced by Drush, you can use the following configuration:

monolog.formatter.drush_or_json:
  class: Drupal\monolog\Logger\Formatter\ConditionalFormatter
  arguments: ['@monolog.formatter.drush', '@monolog.formatter.json', '@monolog.condition_resolver.cli']
  shared: false

The first two arguments are the formatters to use, and the third argument is the condition resolver. The condition resolver is a service that can be used to check if a condition is true or false. In this case, we are using the cli condition resolver, which checks if the current request is a request that comes from the command line.
You can define any condition resolver you want. Just implement the Drupal\monolog\Logger\ConditionResolver\ConditionResolverInterface interface.
The drush_or_json is already provided by the module, you can use it directly (for example in a monolog.service.yml file):

parameters:
  monolog.level.info: info
  monolog.channel_handlers:
    default:
      handlers:
        - name: 'website'
          formatter: 'drush_or_json'

services:
  monolog.handler.website:
    class: Monolog\Handler\StreamHandler
    arguments: ['php://stdout', '%monolog.level.info%']

See the Monolog module readme file for more information: https://git.drupalcode.org/project/monolog/blob/HEAD/README.md

In the next month, I'll concentrate on some other interesting things, like improving the Symfony Messenger module (https://www.drupal.org/project/symfony_messenger), and add profiling support to Drush.

SDC in Drupal core

Lusso Luca — Thu, 14 Sep 2023 09:00:00 +0000

Introduction

There are a lot of contributed modules to build and manage a Drupal theme using components, but none of them has ever been elected as the de facto standard.

However, things have changed with the release of Drupal 10.1 in June 2023. A specific implementation was chosen for inclusion in the Drupal core. Initially developed as a contributed module named Component Libraries: Components, this functionality has been merged into Drupal core as the new SDC experimental module.

What is SDC?

SDC stands for Single Directory Components. It is a way to organize components in a single directory instead of splitting them across different folders. This approach is similar to the one used by React and Vue.js.

The main advantage of this solution is that it is easier to find the code that describes a component. It also simplifies the process of creating a new component, as you just need to create a new folder and add a some files to it.

Finally, it is easier to share components between different projects, as you can just copy the component folder from one project to another (SDC then allows you to override assets like CSS and JavaScript to adapt the component to the design system of the new project).

How to use SDC?

The simplest example we can think of is a button component, but let's try to complicate things a bit by adding some JavaScript and an image.

The first step is to enable the SDC experimental module. Then you need to create a new folder named components in the theme folder or in one of your custom modules (yes, you can have more than one components folder). Those folders contain all the components that will be available in your theme.

The second step is to define a new component. Create a new folder named button in the components folder. This folder will contain all the files related to the button component.

Next, you'll find the code for those files:

button.component.yml: metadata of the component (name, description, props, etc.)
button.twig: Twig code of the component
button.css: CSS code of the component
button.js: JavaScript code of the component
icons/cog.svg: cog icon
README.md: component's documentation

Note how all the files related to the component are named after the component itself, this is mandatory to allow Drupal to automatically declare a library for the component.

Let's start with button.component.yml:

'$schema': 'https://git.drupalcode.org/project/drupal/-/raw/10.1.x/core/modules/sdc/src/metadata.schema.json'
name: button
status: stable
description: A simple button
libraryOverrides:
  dependencies:
    - core/once
props:
  type: object
  properties:
    title:
      type: string
      title: title
      description: Button title
      examples:
        - 'Click me'
    type:
      type: string
      title: Type
      description: Button type
      examples:
        - 'primary'
    icon:
      type: string
      title: Icon
      description: Button icon
      examples:
        - 'cog.svg'
    message:
      type: string
      title: Message
      description: Popup message
      examples:
        - 'Lorem ipsum'
  required:
    - title
    - type
    - icon
    - message

The Twig file may look like this:

 <div {{ attributes.addClass('button') }} data-message="{{ message|default('No message') }}">
   <button class="{{ type }} image-button">
     <img src="/{{ componentMetadata.path }}/icons/{{ icon }}" alt="Image">
     <span>{{ title }}</span>
   </button>
</div>

All the properties defined in the button.component.yml file are available in the Twig file as variables. The componentMetadata variable contains some helpful information, like the path of the component on the filesystem.

We then need some CSS to style the button:

.image-button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: 10px 20px;
  color: #fff;
  cursor: pointer;
  background-color: #124354;
  border: none;
  border-radius: 5px;
}
.image-button img {
  height: 20px;
  margin-right: 10px;
}

To add interactivity to the button we need some JavaScript:

((Drupal, once) => {
  Drupal.behaviors.at_button = {
    attach(context) {
      once('button', '.button', context).forEach((item) => {
        item.addEventListener('click', (event) => {
          event.preventDefault();
          alert(item.dataset.message);
        });
      });
    },
  };
})(Drupal, once);

Finally, the component is ready to be included in one of the Twig templates of your theme (the ones in the templates folder):

{{ include ('example_theme:button', {
    'title': 'Click me',
    'type': 'primary',
    'icon': 'cog.svg',
    'message': 'Lorem ipsum',
  },
  with_context = false)
}}

The final result should look like this:

Try to click on the button and see what happens.

Starting from drupal-code-generator version 3.2.0, a new generator has been added to easily create new components (this replaces the Component Libraries: Generator module that is not compatible with Drush 12). Just run this command and follow the instructions:

drush generate sdc

WebProfiler integration

The latest version of the WebProfiler module (10.1.1) offers full support for collecting and exploring the components used on a page.

On the WebProfiler toolbar, a new counter has been added to the theme widget, showing the number of components used on the page:

Clicking on the counter will open the WebProfiler dashboard, showing all the components used on the page:

At the time of writing, a core patch is required to enable this feature; be sure to apply it before enabling the SDC module.

Another new feature is the ability to explore the list of libraries used on the page (under the Asset data collector). As SDC automatically declares a library for each component, you can use the new pane to find the one used by the button component:

Conclusion

SDC is becoming the de facto standard for building Drupal components, with emerging modules (like No Markup and Single Directory Components: Display) and best practices. More will come in the future.

In this article we have just scratched the surface of this new feature, to learn more we recommend you to read the just published Modernizing Drupal 10 Theme Development book.

In the book you'll find a detailed explanation about how themes work in Drupal 10, how to use SDC, how to integrate with tools like Browsersync and Backstop.js and how to expose your work to frameworks like Storybook.