
One of the problems that Drush solves for developers is the automation and optimization of routine tasks. Drush commands attempt to speed up workflows and tasks that developers and site maintainers would otherwise have to do manually through the UI, or run one-by-one via the command line. One of those tasks is the process of deploying changes to a Drupal application from one environment to another.
The typical Drupal deployment process consists of repeatable steps such as importing configuration changes, applying database updates, and clearing the cache. Drush comes with the handy drush deploy
command that allows you to automate the execution of all of these tasks post code deployment.
In this tutorial we'll:
- Learn about the
drush deploy
command - Discuss when you would use the
deploy
command
By the end of this tutorial you'll know how to use the drush deploy
command in conjunction with other useful deployment-related commands to help automate the task of deploying changes to a Drupal site's configuration and code.
Code generators are great productivity boosters that allow generating scaffolds for common development tasks in Drupal. One of the most common use cases for generators is scaffolding the code required for a custom entity type. Custom entities require many files and complicated annotations in order to function properly. There is a lot of boilerplate code that is more-or-less the same for every entity type. Creating all the files is repetitive, time-consuming, and prone to human error. Generators can help automate this task and make creating your own custom entity types quicker.
In this tutorial we'll:
- Learn how to generate the code for a custom entity with Drush
- Learn about the options that generators provide for custom entities
By the end of this tutorial you should know how to generate custom entities with Drush.
Some Drush commands return a lot of information -- lists of modules, generators, and status reports, for example. It might be hard to find a property you need in the small command window output. Luckily, the output of Drush commands can be piped to other commands, used as a source for imports, settings for CI, and other DevOps tasks.
In order to accommodate all these different use cases, Drush comes with a formatting system that allows you to format and filter output to meet your needs. This system allows to you specify what fields you want returned when the output contains more than one field. It also allows Drush command output to be formatted as JSON, XML, raw PHP, a table, and more.
In this tutorial we'll:
- Learn how to specify the output format -- and what formats are available
- Limit the fields that are returned in a report
- Learn to filter the output to only the data we're interested in
By the end of this tutorial you'll know how to format a Drush command's output to fit your needs.
If you want to change the way an existing Drush command works, you use hooks. Hooks are useful for altering command parameters, options, attributes data, and adding custom logic during particular stages of the command execution process. Drush hooks are conceptually similar to Drupal hooks.
Hooks are methods on a Drush command class with an attribute indicating what hook is being implemented, and thus when the code should be invoked. The code in the methods is executed during specific stages of the command cycle. Developers can use core hooks -- predefined methods that come with Drush core -- or declare a custom hook that other commands can use.
In this tutorial we'll:
- Explore the different core Drush hooks
- Learn which hooks are called at what stage of the command cycle
- View example hook attributes and method implementations
By the end of this tutorial you'll know what types of core hooks are available to you and when they are called.
Adding logging and error handling are an important part of authoring Drush commands. Logs allow developers to get timely feedback from a command and inform users about potential alterations and flags, events to monitor, and the progress of long-running commands. Correct error handling allows for clean exits, meaningful error descriptions, and provides a path forward for developers to fix the errors and accomplish their goals.
In this tutorial we'll:
- Explore the different types of logging messages Drush commands can output
- Learn how to handle errors from within a Drush command
By the end of this tutorial you'll know what types of log messages you can use; how to log success messages, errors, or debug statements from a custom Drush command; and how to handle errors and exceptions.
When the logic of a command depends on user input, it's useful to set up an interactive questionnaire inside the command code. This allows you to provide the user with more context about the input they're providing, and ensure that you collect all the necessary values. This is especially useful when the command uses a pre-defined list of options and the values require memorization. An example of this is the drush cache-clear
command that comes with Drush core. It requires an argument indicating which cache to clear, which you can specify at the command line; however, if you invoke the command with no arguments it will present you with a list of cache bins to choose from and a UI for selecting one.
Drush 9+ can access the Input/Output (I/O) object via the $this->io()
method. This object -- an instance of \Drush\Style\DrushStyle
-- holds information about user-provided input, and utilities for manipulating that input. To ask a user a question, use an io()
object in the command callback method. It can take over the execution flow of the command as needed to stop and gather additional input. The I/O system has various methods for asking confirmation or choice questions such as confirm()
and select()
.
In addition to prompting for input, the I/O object can be used to provide other styling to the command, like progress bars.
In this tutorial we'll:
- Learn how to prompt the user for additional input
- Process the user's answer as part of the command execution flow
By the end of this tutorial you should understand how to prompt a user for additional input for a custom Drush command.
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.
Getting Drupal to run in Docker requires a lot of moving parts. After installing Docker and Docker Compose, we need to select a collection of containers from Docker Hub and create a new docker-compose.yml file. Once we have environment variables and volumes configured, this only gives us the capability of running a Drupal site in Docker.
What if we already have a Drupal site we want to develop using Docker? In this tutorial, we'll show how to modify an existing project to minimize the setup time necessary for switching to a Docker-based environment.
In this tutorial, we'll:
- Describe the best practices for project organization.
- Use an environment file to configure containers.
- Add a Docker-specific settings.php file.
Themes in 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.