Drupal modules need to ensure that any strings of text they add in code can be localized by Drupal's translation system. When our code creates a new <button> element with the text "Toggle forecast" it needs to be done in a way that would allow changing that text to another string, like "Alternar pronóstico", depending on the user's preferred language.
In this tutorial, we'll:
- Define the difference between internationalization and localization and how they allow a Drupal site to be translated.
- Explore the utilities available to module developers to ensure that the user interface strings in their code are translatable.
By the end of this tutorial, you should be able to explain how and why to internationalize the code in your Drupal modules.
Are you ready to learn how to extend and customize Drupal sites in code? The Drupal Module Developer Guide will introduce you to extending Drupal with modules. You will learn foundational concepts and get hands-on practice with a variety of APIs used in Drupal coding and development. We'll be extending the site we built in the Drupal User Guide. If you're new to Drupal site building, we recommend that you walk through the Drupal User Guide first.
Drupal offers module developers several methods for creating different types of links, all defined by module configuration. This tutorial explores these types of links, how they relate to each other, and when to use them.
In this tutorial, we'll learn:
- The nature of menu items, action links, and local task links.
- Examples of each link type in Drupal's UI and their application in our scenario.
- Criteria for selecting the appropriate link type for adding the weather page to site navigation.
By the end of this tutorial, you'll understand the different types of links in Drupal and how they apply to adding navigational elements for custom module pages.
Permissions in Drupal control access to features and functions. Modules define permissions, which allow site administrators to grant or restrict access based on user roles. As a module developer, you'll create new permissions to restrict access to your module's custom features, independent of existing permissions defined by other modules.
In this tutorial, we'll:
- Explore how and where permissions are defined within a module.
- Discuss the concept of static and dynamic permissions in Drupal.
By the end of this tutorial, you'll have a clear understanding of how permissions function in Drupal and their implementation in modules.
Modules can define custom permissions to restrict access to specific routes or page sections. This control allows module developers to provide granular access while enabling site administrators to manage user privileges. We'll add a view weekly weather permission via the anytown module to limit access to the weather page.
In this tutorial, we'll:
- Create an MODULE_NAME.permissions.yml file.
- Define a new permission.
- Use the new permission to restrict access to a route.
By the end of this tutorial, you should be able to define a new permission in a module and use it to control access to a route.
Custom services in Drupal modules encapsulate specific business logic or functionality. In our example, we'll demonstrate moving code required to access a weather forecast API from a controller into a service. This will help make our controller thin and our module code more reusable, testable, and maintainable.
In this tutorial, we'll:
- Explore the advantages of custom services for managing business logic.
- Define the components of a custom service.
By the end of this tutorial, you'll understand why creating custom services is a beneficial practice in Drupal module development.
To access services in Drupal through the service container, you'll need to know the unique machine name of the service. We'll use the example of making HTTP requests to a weather forecast API in the anytown module to demonstrate several methods you can use to identify an existing service's ID.
In this tutorial, we'll:
- Discover existing services and their machine names.
- Take a look at an example service definition.
By the end of this tutorial, you should be able to locate and use existing services in your Drupal module.
Concept: Testing
FreeTesting ensures that code remains reliable and functional. This tutorial introduces the primary types of tests in Drupal: Unit, Kernel, Functional, and FunctionalJavascript -- all executed via PHPUnit. We'll clarify the differences between each type of test and appropriate use cases. As module developers, understanding what to test and how to write tests is vital for robust and maintainable code.
In this tutorial, we'll:
- Identify the primary test types in Drupal and their use cases.
- Emphasize the importance of functional tests in custom module development.
- Introduce the basics of authoring tests in a custom module.
By the end of this tutorial, you should recognize the different types of tests Drupal uses and when and how to use each kind.
Before you can run tests, you'll need to configure your local environment. This setup involves Drupal-specific configuration for PHPUnit and ensuring your environment supports Functional JavaScript tests with a WebDriver client and a compatible browser. The setup process varies based on the development environment. In this tutorial, we're using DDEV as the local environment.
In this tutorial, we'll:
- Install all required dependencies.
- Configure PHPUnit specific to our environment.
- Validate the setup by running a Drupal core test.
By the end of this tutorial, you'll be equipped to run Drupal's PHPUnit tests locally using DDEV.
Functional tests simulate user interactions with Drupal applications, which enables us to test user interfaces and complex workflows. This tutorial guides you through writing functional tests for the anytown module, focusing on custom user registration workflow enhancements.
In this tutorial, we'll:
- Examine functional test structure.
- Test
anytown_form_user_register_form_alter()customizations. - Discuss the functional test execution environment.
By the end of this tutorial, you'll know how to write functional tests that emulate browser interactions with your Drupal application.
Kernel tests in Drupal enable module integration testing with Drupal core systems in a bootstrapped environment. Kernel tests bridge the gap between unit and functional tests. This tutorial focuses on writing kernel tests for the anytown module, specifically to test the ForecastClient service's caching logic and custom username validation.
In this tutorial, we'll:
- Explore the parts of a kernel test.
- Write kernel tests for anytown module features.
- Use mocks and the Drupal container in kernel tests.
By the end of this tutorial, you should be able to get started writing kernel tests to verify your module's integration with Drupal core.
Unit tests are the simplest among Drupal's test types, ideal for verifying code that performs computations. This tutorial guides through writing unit tests for the anytown module, focusing on the ForecastClient service, and illustrates how to use mocks for dependencies.
In this tutorial, we'll:
- List potential unit tests for the anytown module.
- Write tests for
ForecastClientservice logic. - Demonstrate how to mock services in unit tests.
By the end of this tutorial you should be able to write PHPUnit Unit tests for logic in the anytown module.
As of Drupal 10.2, most plugin types use PHP attributes for discovery and metadata.
In this tutorial, we'll:
- Provide a recipe for implementing PHP attribute-based plugins.
- Demonstrate how to figure out where the code and metadata should live for PHP attribute-based plugins.
By the end of this tutorial you should have a recipe for getting started with implementing PHP attribute-based plugins, and a better understanding of how to figure out the details required to implement a given plugin type.
PHP attributes are a native PHP language feature, introduced in PHP 8.0, that provide a way to add metadata to classes, methods, properties, and functions in PHP code.
In Drupal, this metadata is used by the plugin system to aid in the discovery and configuration of plugin instances. As a Drupal developer, it's important to understand how to recognize, read, and write PHP attributes, as you'll encounter them when working with plugins.
In this tutorial we'll look at:
- What PHP attributes are
- The use case for attributes in Drupal
- An overview of the attribute syntax
By the end of this tutorial, you should understand how attributes are used in Drupal and how to write them in your own code.
Prior to Drupal 10.2 most plugin implementations required the use of annotations alongside a PHP class. Now Drupal supports and recommends the use of PHP attributes instead. During the transition, most developers will still need to know how to recognize and implement annotation-based plugins.
In this tutorial we'll:
- Provide a recipe for implementing annotation-based plugins.
- Demonstrate how to figure out where the code and metadata should live for annotation-based plugins.
By the end of this tutorial you should have a recipe for getting started with implementing annotation-based plugins, and a better understanding of how to figure out the details required to implement a given plugin type.
Many of Drupal's APIs that look like a bunch of configuration in a YAML file (migrations, menu links, etc.) are actually plugins in disguise. The YAML from these files is used as arguments to a generic PHP plugin class which then behaves differently depending on the provided values. As a developer, you probably don't need to know that menu links are plugins, but it can be helpful when debugging or just trying to get a better understanding of the big picture.
In this tutorial, we'll:
- Learn about how YAML-based plugins work
- Discuss how to find the implementation details for YAML-based plugins
- Walk through an example of implementing a YAML-based plugin
By the end of this tutorial, you should be able to recognize a YAML-based plugin definition, and author your own.
In this tutorial, you'll learn how to add a property to a configuration entity in Drupal. Previously, we created a configuration entity called Transcode Profile and learned about the files and code that compose a configuration entity. Now, we'll add a new property called codec to this configuration entity and learn some new concepts in the process.
In order to add this new property to our custom configuration entity, we'll need to update our schema file, configuration entity forms, the entity list builder class, and add getter and setter methods to our main TranscodeProfile class.
In this tutorial, you'll learn about the two types of configuration data: simple configuration and configuration entities. By the end of this tutorial, you should have a better understanding of which type of configuration to use in your module.
In this tutorial we’re going to walk through the process of creating a custom configuration entity in Drupal in a custom module. We'll be using Drupal Console's generate:entity:config command to create and update the files in our Transcode Profile example module. After Drupal Console has generated and updated the files for our configuration entity, we'll walk through each file and see how they define data structure, metadata, an administrative interface, and menu links for a configuration entity in Drupal.
By the end of this tutorial, you should be able to:
- Use Drupal Console to generate a configuration entity
- Identify files associated with a configuration entity and summarize the purpose and function of the code inside each file
- Find other examples of configuration entities in Drupal core
As a developer, within a module, you can define settings for the module and provide a configuration form for administrators to update the values of those settings. In this tutorial, we'll create a configuration settings form for a module and define default values for each setting. We'll use Drupal Console, a command-line utility for Drupal to do some code scaffolding and speed up the process.
By the end of this lesson, you should be able to get a basic settings form up and running inside a custom module complete with default settings and a menu link.