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
ForecastClient
service 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.
Keep Drupal Up-To-Date
GuideGeneral Drupal Development
CoursePHP namespaces provide a way in which to group related classes, interfaces, functions and constants. Drupal uses PSR-4 namespaces to autoload the correct PHP class from a file, accommodating variations in site structures.
Upgrade Drupal
CourseInstall and Update Drupal
CourseMedia source plugins provide the link between media entities in Drupal and the actual media asset itself. They are the code that understand the difference between an image, a video, and a Tweet, and perform the translation that allows the media ecosystem to treat all media entities equally. For example, local image files, and remote YouTube videos, can both be catalogued in a similar way as media entities, but they need very different handling when it comes to displaying them.
Media sources are represented as plugins, there are a handful in Drupal core, and a developer can add new plugins to represent any type of media your application needs to catalogue.
In this tutorial we'll learn:
- How media source plugins relate to Media Types
- The responsibilities of a media source plugin
By the end of this tutorial you should be able to define the role of a media source plugin and understand what's required to define your own.
The Drupal core Media Library module provides an enhanced user interface for locating Media entities and attaching them to an article. It's a drop-in replacement for the default entity reference widget which uses a not very intuitive autocomplete field. Using the Drupal core Media Library module requires minimal configuration.
If you want to provide content creators with a gallery-like library of Media entities that they can browse through in order to find the ones they want to add to their content, the Media Library is the easiest way to do it. It can be configured to work with both Media fields and the CKEditor powered WYSIWYG editor commonly used for editing the body field of Drupal nodes. There's really no reason not to use it.
In addition to providing a better UI for locating existing Media entities, the Media Library provides a way to create new Media entities right from the content creation form. This prevents an otherwise confusing requirement where Media entities need to be created, via a different set of forms, before they can be used.
In this tutorial we'll:
- Install and configure the Media Library module to work with Media fields
- Use the user interface provided by the Media Library to improve the experience of finding and selecting Media entities to associate with a piece of content
By the end of this tutorial you'll know how to replace the default entity reference widget used for selecting Media entities with the much improved Media Library UI.
Media entities, like any content entity, work great with all the different features Drupal provides for changing the way things are displayed: view modes, Layout Builder, theme templates, and more. We're big fans of using view modes to create a component-like design system where entity types have view modes representing the different context in which they're displayed. Then we theme the view modes. This works great for displaying Media entities associated with a page and for changing the way that Media assets are displayed within the Media Library browser.
In this tutorial we'll:
- Create Hero and Sidebar view modes for Media entities
- Configure the Image Media type to use the new view modes and style each one differently
- Use the new view modes to render Image Media assets within a Layout
- Update the Media library view mode that's used by the Media Library browser to display additional information alongside the thumbnails used when selecting Media to attach to a page
By the end of this tutorial you should be able to change the way that Media assets are displayed by using view modes and display formatters in a Drupal site.
It's not uncommon to patch, or customize, contributed modules during the lifetime of a site. It's important to know if you've done so when planning for a migration since you'll want to be sure that you don't lose any customizations when you start using an updated version of a module.
In this tutorial we will walk through using the Hacked! module to check for any alterations to your Drupal code base.