While Drush empowers all Drupal users with its commands, it's even more powerful when used in combination with scripting solutions such as Composer and Bash. Scripts can be used to power post-deployment tasks like importing new configuration or clearing the cache, as part of CI processes to sync a database from one environment to another, to run background processes on the server such as imports and migrations, search indexing, running cron, and much more. If you want to write Bash (or any other scripts) that interact with a Drupal site, then Drush is the tool for you.
In this tutorial we'll:
- Learn how to use Drush commands within Composer and Bash scripts
- Learn how to chain multiple Drush commands together in a script
By the end of this tutorial you'll know how to use Drush as part of a script that automates common or tedious tasks.
When you manage many Drupal websites, you may perform repetitive tasks that are common across all of your sites. In our experience, this usually relates to having a personal preference for how certain tasks are accomplished. For example: maybe you like to make backups of the database and files in a specific way before testing upgrades, or you have a set of scripts for running scans of core web vitals. Although these tasks can be bundled into a custom module, it could be useful to create a site-wide Drush command instead. Site-wide commands can be installed with Composer, managed in a separate Git repository, and act as a project dependency. This way they are easy to maintain through a separate upstream. Changes to this code will be reflected on all the sites where it's used.
In this tutorial we'll:
- Declare a custom site-wide Drush command
- Demonstrate how to use Composer to manage a package that contains a Drush command
By the end of this tutorial you'll be able to create a site-wide Drush command and manage the code with Git and Composer.
The Drupal Entity API makes it easy to define new custom content entity types. And in most cases whenever you want to store custom content in Drupal you should use the Entity API instead of making CRUD queries directly to the database. This ensures your code is more consistent, and allows you to take advantage of all the features of the Entity API like access control, Views module integration, and automatic JSON:API support. As well as making it easier for others to extend your custom content by ensuring all the proper hooks and lifecycle events get invoked when new content items get created, updated, and deleted.
In this tutorial we'll:
- Walk through the process of creating a custom content entity
By the end of this lesson you'll be able to create your own custom content entity contained in a module.
One of Drupal's more powerful features is the fine-grained ability to control permissions and control access to content. The Entity API helps enable this functionality by providing an interface to help define access control.
In this tutorial we'll:
- Look at how access control is handled, using Drupal core as an example.
- Demonstrate how to implement access control in a custom module.
- Learn about the hooks that allow developers to modify access control for entities provided by another module.
By the end of this tutorial you should have a better understanding of the entity access control system and how to work with it.
Entities are the building blocks that make up just about everything on a Drupal site. Regardless of whether entities provide configuration information or content, they are absolutely crucial to Drupal's data model.
In this tutorial we'll:
- Look at the overall class hierarchy between the various entity types to see how they're related.
- Examine differences between configuration and content entities in the code that defines them.
- Look at some of the core code required to create an entity type.
By the end of this lesson you should be able to use an example to create a custom entity type in code.
Often when building a site in Drupal you'll find yourself wanting to display a list of nodes, or find entities created by a particular author, or locate some content based on a particular set of criteria. Rather than querying the database directly, Drupal provides a helper class, EntityQuery
, to make things a bit easier. The EntityQuery
class will probably look very familiar to you if you're familiar with the Database API, or the EntityFieldQuery
class in Drupal 7.
In this tutorial we'll:
- Go through several examples of using
EntityQuery
to find subsets of content. - Demonstrate how to iterate over the results of an
EntityQuery
query.
By the end of this tutorial, you should understand how to use entity queries to create custom sets of data from entities.
Entity API Overview
FreeWhen learning Drupal development, it won't be long before you encounter the word "entity" and the Entity API. But what are entities in Drupal? How can you use them to build your site? When should you use the Entity API?
This tutorial will explain Drupal's Entity system from a high level. We'll look at:
- The main problems the Entity system solves
- Key terms you should know
- Key concepts we'll explore as we dive into Drupal's Entity API
By the end of this tutorial you should be able to explain the problems that the Entity API solves, and when you should use it in your own code.
Drupal includes the Symfony Validator component, and provides an Entity Validation API to assist in validating the values of fields on an entity. By using the Entity Validation API you can ensure that you're validation logic is applied to Entity CRUD operations regardless of how they are triggered. Whether editing an Entity via a Form API form, or creating a new Entity via the REST API, the same validation code will be used.
Using the Entity Validation API in order to validate the value of a field on an entity requires:
- Defining (or choosing) a constraint plugin
- Defining (or choosing) a validation plugin
- Adding the constraint to the field definition
In this tutorial, we'll look at how this Validation API works and how it can be used in custom code to ensure our entities have properly constructed values. We'll look at how this validation works in Drupal core and how we can add our own additional constraints. We'll also see how to work with the error messages returned from the validator when our entity doesn't pass validation.
Creating a container set to support Drupal development requires some specialized knowledge. Now that we understand containers, images, how to use Docker Compose (docker-compose
), and how to select images on Docker Hub, we're ready to build a container set to support Drupal development.
In this tutorial, we'll:
- Select images of software that we'll need to run Drupal
- Create a new Compose file
- Configure bind volumes and environment variables to support the site
- Test the configuration
See Dockerize an Existing Project if you already have Drupal installed.
Customizing the available regions in your theme is one of the first things you'll do when creating your own themes. Doing so gives you complete control over where content is displayed on the page, and the markup involved. Adding regions to a theme is a two-step process that involves editing your theme's THEMENAME.info.yml file and updating your page.html.twig file.
In this tutorial we'll:
- Declare one or more new regions in our themes THEMENAME.info.yml file.
- Output the content of those regions in our theme via the page.html.twig file.
By the end of this tutorial you should be able to add or edit the regions a theme provides. Also, you'll ensure that blocks placed into regions are displayed by outputting the regions in the page template.
Contributed and custom themes can ship with a thumbnail screenshot that will be used to represent the theme when listing themes in the administration UI.
In this tutorial you'll learn how to:
- Prepare your site for the screenshot
- Create a screenshot of your theme
- Define a screenshot file for your theme in the THEMENAME.info.yml file
Preprocess functions are specially-named functions that can be used to add new variables to a Twig template file. They are commonly used by themes to add new variables based on custom PHP logic and simplify accessing the data contained in complex entity structures. For example: adding a variable to all node.html.twig template files that contains the combined content a couple of specific fields under a meaningful name like {{ call_to_action }}
. Modules use preprocess functions to expose the dynamic data they manage to Twig template files, or to alter data provided by another module based on custom logic.
In this tutorial we'll learn how to:
- Use PHP to perform some complex logic in our theme.
- Store the resulting calculation in a variable.
- Make that variable available to a Twig template file.
Example use cases for adding variables with preprocess functions include:
- Anytime calculating the value to output in a template requires logic more complex than an if/else statement.
- Anytime the desired value requires additional string manipulation beyond what can be easily accomplished using an existing Twig filter or function.
By the end of this tutorial you should be able to expose new variables to a Twig template file by defining a preprocess function in either a module or a theme.
Twig has a special syntax for accessing array keys and objects, also known in Twig as variable attributes. In this tutorial, we'll cover the period or dot (.
) operator to access a variable attribute, as well as subscript or square-bracket syntax, useful for when the key of the array contains special characters, like a dash (-
) or pound sign (#
). We'll also look at the logic Twig uses to find the matching attribute in an array or object.
Once you've defined an asset library you'll need to tell Drupal when you want to add the CSS and JavaScript that it includes to the page. Ideally you'll do so in a way that allows Drupal to only add the corresponding assets on pages where they are needed.
You can attach a library to all pages, a subset of pages, or to elements in a render array. This allows you to have some assets that are global, and others that get loaded on an as-needed basis. To attach a library you'll need to know both its name and prefix, and then use one of the techniques outlined below to let Drupal know when to include it.
In this tutorial, we'll look at attaching asset libraries:
- Globally, via your THEMENAME.info.yml file
- Conditionally, via a preprocess function using the
#attached
render array property - Inside of a Twig template file
By the end of this tutorial you should be able to attach asset libraries in various different ways depending on your use case.
It's probably not too surprising that a library called Backbone aims to provide structure to your front-end JavaScript code and applications. In this tutorial we'll take a look at how Backbone.js goes about achieving that goal, and how you can make use of it on your Drupal site. We'll first take a high-level look at the main components that make up the Backbone.js library. With that basic understanding in place we'll look at an example of how you might integrate Backbone.js into a Drupal site.
Drupal's Breakpoint module defines a "breakpoint" plugin type that modules or themes can implement via a breakpoints configuration file. So, in order to make their breakpoints discoverable, themes and modules define their breakpoints in a THEME-OR-MODULE.breakpoints.yml file located in the root of their directory.
In this tutorial, you'll learn about the structure of a breakpoints configuration file and why you would want to use one. We’ll cover the kinds of metadata you can include in a breakpoint file, including key, label, mediaQuery, weight, multipliers, and breakpoint group. Throughout, we'll look at some examples of breakpoint configuration files available in Drupal themes and modules.
The routing system can get dynamic values from the URL and pass them as arguments to the controller. This means a single route with a path of /node/{node}
can be used to display any node entity. Route parameters can be validated, and upcast to complex data types via parameter conversion. If you ever want to pass arguments to the controller for a route, you'll use parameters to do so.
In this tutorial we'll:
- Define what parameters (slugs, placeholders) are and what they are used for in a route definition.
- Explain how URL parameters are passed to a controller.
- Define parameter upcasting.
By the end of this tutorial, you should be able to explain how to define a route that uses parameters to pass dynamic values to the route controller, and explain how parameter upcasting works.
Every route should define its access control parameters. When you define routes in a module, you can limit who has access to those routes via different access control options. Route-level access control applies to the path. If your route defines a path like /journey/example
, the access control configuration will determine whether to show the current user the page at the path defined by the route, or to have Drupal serve an "HTTP 403 Access Denied" message instead.
In this tutorial we'll look at different ways of adding access control to a route including:
- Access based on the current user's roles and permissions
- Access based on custom logic in a callback method
- Logic in an access checker service
By the end of this tutorial, you should be able to add access control logic to your custom routes that will meet any requirement.
When defining a route and subsequently displaying the page, often we need to calculate the page title based on route parameters or other logic. In these cases, we can't just hard code the value into the _title
configuration of the route. To set a dynamic title for a page, we'll use the route's _title_callback
option, and point to a PHP callback that contains the logic that computes the title of the page.
In this tutorial we'll:
- Learn how to use the
_title_callback
route configuration option to dynamically set a page title - Explain how arguments are provided to the title callback method
- Update the route and controller from a previous tutorial to use a dynamic title callback
By the end of this tutorial, you should be able to configure a route so that its title can be set dynamically using route parameters, instead of hard-coding the title with a static string of text.
Let's write some code that will allow us to see route parameters in action. We'll define a new route with a path like /journey/42/full but where 42
can be any node ID, and full
can be any view mode. When a user accesses the path we'll pass the dynamic parameters from the URL to the controller. The controller will then load the corresponding node and render it using the provided view mode, and return that to display on the page.
By the end of this tutorial you should be able to:
- Use dynamic slugs in a route to pass parameters to the route controller.
- See how Drupal will upcast a value like the node ID, 42, to a
Node
object automatically. - Explain what happens when you visit a URL that matches a route but the parameters don't pass validation.
By the end of this tutorial, you should be able to pass dynamic values from the URL to a route's controller.