11.0.x

Upgrade to Drupal 11

Admin — Thu, 31 Oct 2024 21:00:13 +0000

Upgrade to Drupal 11 Admin Thu, 10/31/2024 - 16:00

Backend and Infrastructure, Site Administration

11.0.x

There’s no one-size-fits-all path to upgrade from Drupal 10 to Drupal 11, but there is a set of common tasks that everyone will need to complete.

In this tutorial we’ll:

Explain the differences between Drupal 10 and Drupal 11 that affect the upgrade path.
Walk through the high-level steps required to upgrade from Drupal 10 to Drupal 11.
Provide resources to help you create an upgrade checklist and start checking items off the list.

By the end of this tutorial you should be able to:

Explain the major differences between Drupal 10 and 11.
Audit your existing Drupal 10 projects for Drupal 11 readiness, and estimate the level of effort involved.
Start the process of upgrading your site from Drupal 10 to Drupal 11.

There’s no one-size-fits-all path to upgrade from Drupal 10 to Drupal 11, but there is a set of common tasks that everyone will need to complete.

In this tutorial we’ll:

Explain the differences between Drupal 10 and Drupal 11 that affect the upgrade path.
Walk through the high-level steps required to upgrade from Drupal 10 to Drupal 11.
Provide resources to help you create an upgrade checklist and start checking items off the list.

By the end of this tutorial you should be able to:

Explain the major differences between Drupal 10 and 11.
Audit your existing Drupal 10 projects for Drupal 11 readiness, and estimate the level of effort involved.
Start the process of upgrading your site from Drupal 10 to Drupal 11.

Goal

Create a Drupal 11 upgrade checklist, and understand what’s required to complete the items on the list.

Prerequisites

What Is Deprecated Code?
You may need to first Update Drupal's Minor Version to ensure your site is on Drupal 10.3.x or higher.

Drupal 11 released August 2, 2024

Drupal 11 was released on August 2, 2024. Learn more about what's included in Drupal 11 and read the Drupal 11.0.0 release notes.

Use Upgrade Status module on your Drupal 10 site to help you plan your upgrade. This module provides a report of what modules on your site have a Drupal 11-compatible release.

Note: Your site must be on Drupal 10.3.0 or later to upgrade to Drupal 11. Update your Drupal 10.x site to the latest version of Drupal 10.3.x or later before upgrading to Drupal 11. See Update Drupal's Minor Version.

Quickstart

Here's the quick version; keep reading below for more details.

composer require 'drupal/core-recommended:^11' 'drupal/core-composer-scaffold:^11' 'drupal/core-project-message:^11' --update-with-dependencies --no-update
# If you have drupal/core-dev installed
composer require 'drupal/core-dev:^11' --dev --update-with-dependencies --no-update
# If you have Drush installed (check recommended version)
composer require 'drush/drush:^13' --no-update
# Now, actually perform the update to the code itself.
composer update

# Then run any updates.
drush cr -y
drush updb

# Export configuration changes (and don't forget to commit the changes).
drush cex -y

Differences between Drupal 10 and Drupal 11

From a technical perspective Drupal 11.0.0 is Drupal 10.3.0 with all deprecated code removed.

Drupal 11 also includes updates to many of Drupal core’s dependencies, including CKEditor, Symfony, Twig, jQuery, and others. If you’ve got code in your project that relies on an older version of these dependencies, that code will need to be updated, too.

Notable 3rd-party dependency updates

Drupal 10	Drupal 11
CKEditor 5.x	CKEditor 5 v42.0.2
Symfony 6.x	Symfony 7.1.1
Twig 3.5.0	Twig 3.9.3
jQuery 4.x	jQuery 4.0.0-beta2

Replace or uninstall deprecated core modules

Core modules that were marked as deprecated in Drupal 10 were removed in Drupal 11 and are now considered obsolete in Drupal 11. If your Drupal 10 site is using a deprecated core module, you should switch to a module that is compatible with Drupal 11. Upgrade Status module can give you recommendations on alternative modules. In most cases, the deprecated core module was ported to a contributed project. And so, you can install the ported contributed module as a replacement. If you have a deprecated module installed but your site is not using it, you should uninstall it before attempting to upgrade.

Removed modules

These core modules were deprecated in Drupal 10 and removed in Drupal 11.

Learn more about deprecated and obsolete extensions and what to do if your site uses them.

When should I upgrade to Drupal 11?

Short answer: when your code is ready.

The primary consideration should be whether the contributed modules you rely on, and your own custom modules, are Drupal 11 compatible. Once they are, there is no reason to not upgrade.

If you're using Drupal 10 you have until mid-late 2026 to complete your upgrade. At that point, Drupal 12 will be released, Drupal 10.5.x will be unsupported, and Drupal 10 will have reached its end-of-life. There is also the current Drupal 7 end-of-life date: January 5, 2025.

Refer to the Drupal core release schedule for details and potential updates to these dates.

Drupal 11 upgrade checklist

Make sure you can check off all the items in the list before you upgrade to Drupal 11.x:

Update to Drupal 10.3.x (or later)

Before you can upgrade your site to Drupal 11 it needs to be on 10.3.0 or later. Update your site to the latest release of Drupal 10 before upgrading to Drupal 11.

If you need to update your Drupal 10 site, first learn how to perform a minor version update, then come back to this tutorial.

Update all your contributed projects

Important note: You should update all your contributed modules and themes to Drupal 11 compatible versions while you're still on Drupal 10.

It's a good idea to update all your contributed modules and themes to their latest versions as well. Before you can upgrade Drupal core to version 11, you'll need to ensure that all of your contributed projects are already Drupal 11 compatible. In most cases this will mean updating to the latest version. In some cases this may require additional work if the module isn't already Drupal 11 ready.

Look at the project's page on Drupal.org for more details about compatibility:

Acquia has created a useful tool for checking compatibility.

These are good for getting an estimate of what's going to be involved for your project.

Tip: Check Extend > Uninstall for any deprecated modules (they will be listed at the top).

Use Upgrade Status module

When you're ready to start working on the Drupal 11 readiness of the modules installed on your site, use the Upgrade Status module on your current Drupal 10 site to generate a report. Use the 4.x version for Drupal 10 to 11 upgrades.

See the Upgrade Status project page for instructions on how to update development dependencies and download the project with Composer.

After downloading the module with Composer, install the module with drush en upgrade_status or via the Extend administrative page.

Use the Manage administrative menu, navigate to Reports > Upgrade status to see the report and take action.

If a module isn't Drupal 11 compatible you've got a few options:

Update it yourself. This similar to updating custom code. (See below.)
Wait for a future release of an updated Drupal 11-compatible version.
Hire someone to do the updates for you.

We recommend starting with your custom code. And once that's done, come back to your contributed modules and figure out which ones are the most critical for your project and see what you can do to help update them for Drupal 11. In many cases there's likely a patch already available and waiting for community members to test it out.

Update your custom code

If your project has custom modules or themes, it's your responsibility to ensure that that code is compatible with Drupal 11. Using an IDE with support for the @deprecated annotation can help you identify deprecated code. Drupal core deprecations (and new features) will have change records in Change records for Drupal core.

You can use Upgrade Status to scan these projects as well. And then you'll need to remove all use of deprecated APIs. Learn more about what deprecated code is and how to deal with it.

Tip: Even if you're not planning to upgrade to Drupal 11 now, you should start doing this. It'll save time in the future, and since Drupal 11 is backward-compatible with Drupal 10.3.0, it shouldn't affect your existing site.

Verify your hosting meets the new requirements

The system requirements for Drupal have changed. (See also the "Platform requirements changes" heading in the release notes.) You'll want to make sure your web server, PHP, and MySQL/MariaDB are all running compatible versions. Upgrade Status will indicate if the Environment is incompatible on its report as well. (This is only useful if the environment on which you're running Upgrade Status is the same as the environment in which you'll be hosting your Drupal 11 site.)

Check the Upgrade Status report

Using the Manage administrative menu, navigate to Reports > Upgrade status and, if necessary, click the Check available updates link under the Gather data column.

Once you have addressed all blockers to a Drupal 10 upgrade, you will see "N/A" in the Fix incompatibilities column and "100%" in the Relax column (along with other information).

Upgrade Drupal core

Sites running Drupal 10.2.x or earlier must first update to at least 10.3.x before updating to Drupal 11. See Update Drupal's Minor Version.

The instructions below assume you that your Drupal 10 project is using Composer to manage dependencies, and that you either started from the drupal/recommended-project Composer template or you've updated your composer.json to use the drupal/recommended-project's approach to scaffolding. If you're unsure, look for entries like "drupal/core-recommended": "^10.3", and "drupal/core-composer-scaffold": "^10.3" in your composer.json file. This is a good indication that you're using the current recommend approach.

Note: Using the --no-update flag updates the composer.json entries without attempting to resolve and download any files. This allows us to batch updates to projects and avoid a "chicken-or-egg first"-type of issues with shared dependencies. You can also edit the version constraints in composer.json manually.

Update `drupal/core-dev` (if applicable)

If you have the drupal/core-dev dependencies installed you'll need to update those with:

composer require drupal/core-dev:^11.0 --dev --no-update --update-with-dependencies

Update `drupal/core-*` projects

Then update the drupal/core-recommended, drupal/core-composer-scaffold, and drupal/core-project-message projects:

composer require drupal/core-recommended:^11.0 drupal/core-composer-scaffold:^11.0 drupal/core-project-message:^11.0 --no-update --update-with-all-dependencies

Run `composer update`

Then tell Composer to try and resolve and download all the new code:

composer update

If this is successful, you'll see lines like the following in the output:

  - Upgrading drupal/core-dev (10.3.5 => 11.0.5)
  - Upgrading drupal/core (10.3.6 => 11.0.5): Extracting archive
  - Upgrading drupal/core-recommended (10.3.6 => 11.0.5)

If you get any errors you'll need to troubleshoot what's causing the issue. We've tried to provide guidance on some common errors below.

Put your site in maintenance mode

Put your site in maintenance mode before continuing. If you don't, you may end up with a backup you can't revert to.

drush state:set system.maintenance_mode 1
drush cache:rebuild

Or, using the administrative UI:

Maintenance mode: Configuration > Development > Maintenance mode (admin/config/development/maintenance)
Clear caches: Configuration > Performance (admin/config/development/performance)

Make a backup

Back up the database, as the next steps will make changes to your database schema and are not reversible.

Deploy your code

Deploy your code per your normal workflow.

Check for and run database updates

Assuming Composer was successful at upgrading your site's dependencies to Drupal 11, check for database updates. (If Composer was not successful, you need to deal with those errors before continuing. See below for troubleshooting tips.)

Using Drush:

drush updatedb

Or navigate to /update.php and navigate through the Drupal database update wizard.

Take your site out of maintenance mode

After database updates have successfully run, take your site out of maintenance mode and rebuild caches.

drush state:set system.maintenance_mode 0
drush cache:rebuild

Celebrate! You've upgraded to Drupal 11!

Congratulations! You've upgraded your site to Drupal 11!

Troubleshooting a Drupal 10 upgrade to Drupal 11

Problem: Permission denied updating files in sites/default/

In some cases you may need to modify the permissions on the sites/default/ directory, and files within it, so that they can be modified.

Solution: Set them to something more permissive:

chmod 777 web/sites/default
find web/sites/default -name "*settings.php" -exec chmod 777 {} \;
find web/sites/default -name "*services.yml" -exec chmod 777 {} \;

Important!: Remember to set permissions back after completing the update:

chmod 755 web/sites/default
find web/sites/default -name "*settings.php" -exec chmod 644 {} \;
find web/sites/default -name "*services.yml" -exec chmod 644 {} \;

Problem: Composer can't install packages

If running composer update results in message saying, "Your requirements could not be resolved to an installable set of packages.", there's a good chance that one or more of your contributed modules isn't Drupal 11 compatible. (Or at least the current release version of the project isn't.)

Solution: Look for lines like this in the output:

- drupal/recurly 1.5.0 requires drupal/core ~8.0 -> satisfiable by drupal/core[8.8.6, 8.0.0, 8.0.0-beta10, ...

This indicates that the drupal/recurly project requires Drupal 8.x, but we're asking for Drupal 9.x, therefore resulting in an incompatible set of dependencies.

(While this is an example from upgrading from 8 to 9, you may encounter a similar situation for a particular project when you upgrade from 10 to 11.)

If there's a -dev version of the module that you know is compatible with Drupal 11 you could try installing that.

Example:

composer require drupal/recurly:1.x-dev --no-update

If there's a patch in the issue queue see the next tip.

Problem: Contributed module only has a patch

Often times modules without a Drupal 11-compatible release will have a patch in the issue queue that makes the module work with Drupal 11, but hasn't been committed by the project maintainers yet.

This can result in a sort of race condition, where Composer can't download the required module because it's not presenting as Drupal 11 compatible, so you need to apply a patch, but Composer can't apply the patch, if it can't resolve the dependency tree first.

Solution: Try the Lenient Composer Plugin.

In the transition from Drupal 8 to 9, a lenient Composer endpoint was created to remove this barrier. For the same situation for Drupal 9 to 10 and 10 to 11 upgrades, a Composer plugin was created: Lenient Composer Plugin.

Recap

In this tutorial, we looked at what's involved in making the transition from Drupal 10 to Drupal 11. This included going over the differences between the two, auditing your custom and contributed modules for compatibility, learning how to make things Drupal 11 compatible while still using Drupal 10. And then finally upgrading Drupal core once everything else is ready, and some troubleshooting tips for common problems.

Further your understanding

Most of the Composer commands above can be replicated by directly editing your composer.json file, and then running composer update.
If you're using Drupal 7, upgrading to Drupal 11 still requires a major migration. See our Learn to Migrate to Drupal guide.

Additional resources

Drupal 11.0.0 release notes (Drupal.org)
Drupal 10 will be supported until the release of Drupal 12 in mid-late 2026 (Drupal.org)
How to upgrade from Drupal 10 to Drupal 11 (Drupal.org)
Preparing your site to upgrade to a newer major version (Drupal.org)
Deprecated and obsolete extensions (Drupal.org)
Use Composer with Your Drupal Project (Drupalize.Me)
Troubleshoot Common Composer Issues (Drupalize.Me)
Drupal Lenient Composer Plugin (GitHub.com)
Changes required for PHPUnit 10 compatibility (Drupal.org)

October 31, 2024

Implement a Plugin Using PHP Attributes

Admin — Fri, 18 Oct 2024 23:20:24 +0000

Implement a Plugin Using PHP Attributes Admin Fri, 10/18/2024 - 18:20

Module Development

11.0.x

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.

October 17, 2024

Implement a YAML Plugin

Admin — Fri, 18 Oct 2024 23:19:24 +0000

Implement a YAML Plugin Admin Fri, 10/18/2024 - 18:19

Module Development

11.0.x

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.

October 17, 2024

Implement a Plugin Using Annotations

Admin — Fri, 18 Oct 2024 23:19:24 +0000

Implement a Plugin Using Annotations Admin Fri, 10/18/2024 - 18:19

Module Development

11.0.x

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.

October 17, 2024

PHP Attributes

Admin — Fri, 18 Oct 2024 23:19:24 +0000

PHP Attributes Admin Fri, 10/18/2024 - 18:19

Module Development

11.0.x

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.

October 8, 2024

Audience and Approach

Admin — Wed, 01 May 2024 16:01:03 +0000

Audience and Approach Admin Wed, 05/01/2024 - 11:01

Module Development

11.0.x

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.

Goal

Decide if this guide is for you.

Prerequisites

None.

Audience

We created the Drupal Module Developer Guide for developers familiar with PHP but new to Drupal module development. We assume you have a foundation in PHP development and want to expand your skills into Drupal. This guide is not for absolute beginners in coding or PHP. This guide is also suitable for folks with development experience in Drupal 7 but who need to get familiar with the latest API.

You'll have the most success with this guide if you:

Understand PHP and object-oriented programming concepts.
Are familiar with common site building and administration tasks in Drupal.
Can navigate files and execute commands in a Terminal.
Are familiar with downloading modules using Composer and installing them.

Approach

In this guide, we use a project-based learning approach. You'll have the best learning experience if you read the guide in order and in full. Tutorials often build upon previous work. As you progress through the guide, we'll refactor and expand code examples from previous tutorials, to give you hands-on practice with new concepts and patterns.

Learning objectives

Upon completing this guide, you should be able to:

Plan the content architecture for a custom Drupal module.
Build a module using Drupal core APIs and recognizable design patterns.
Write secure code that adheres to Drupal coding standards and includes automated tests.
Find documentation and blog posts on advanced topics, to expand your knowledge and skills.
Engage with the global Drupal community.

Recap

The Drupal Module Developer guide is for PHP programmers who are familiar with Drupal site building and administration but new to module development in the latest version of Drupal. This guide uses a project-based approach with a guiding scenario that was originally introduced in the Drupal User Guide.

Further your understanding

Familiarize yourself with the project-based learning scenario we'll use in this guide at Guiding Scenario.

Additional resources

Drupal User Guide (Drupalize.Me)
PHP for Beginners Part 1 (Drupalize.Me)
PHP for Beginners Part 2 (Drupalize.Me)
PHP for Beginners Part 3 (Drupalize.Me)
Object-Oriented PHP (Drupalize.Me)

May 2, 2024

Guiding Scenario

Admin — Wed, 01 May 2024 16:01:02 +0000

Guiding Scenario Admin Wed, 05/01/2024 - 11:01

Module Development

11.0.x

We'll be working with the Anytown Farmers Market site, which we built in the Drupal User Guide. Our goal is to extend and enhance this site using custom modules, to fulfill project-specific requirements. We use a narrative approach, which we hope will help you better understand the real-world applications of module development in Drupal.

Goal

Explain the guiding scenario which ties together all the code examples in this guide, and provides a project-based learning approach to Drupal module development.

Prerequisites

You're familiar with the Anytown Farmers Market site that we covered in the Drupal User Guide.
You're familiar with the Drupal site building and administrative tasks and concepts taught in the Drupal User Guide.

The guiding scenario

You are a developer tasked with adding new features to the Anytown Farmers Market site. You can't add the features with Drupal's site building tools or any existing contributed modules, so you'll need to write some custom code. You're familiar with PHP, and web development using a CMS or framework, but this is your first time writing custom code for Drupal.

You need to add the features below.

Weather forecast feature

A new page at the URL, /weather, that shows the current weather forecast and details about any weather-related happenings for the next market weekend market. For example, an ice skating rink that's open in the winter or a market closure due to icy conditions. You'll need to retrieve the forecast using a remote API, and a site administrator should be able to fill out a form to publish current weather-related happenings.

Vendor attendance feature

A feature that enables vendors to say that they plan to attend the upcoming market and who the contact person is. While we could update this information through the vendor node edit form, we want a simplified UI, since we're asking vendors to do this every week.

As you read through the guide and try out the described tasks, you may choose to follow the scenario as-is, or customize the tasks to suit another purpose.

Let's get started.

Recap

We introduced the guiding scenario and project requirements which we'll fulfill in this guide.

Further your understanding

Can you write user stories that outline the work you'll be doing for this project?

Additional resources

Drupal User Guide (Drupalize.Me)

May 2, 2024

Concept: What Are Modules?

Admin — Wed, 01 May 2024 16:01:01 +0000

Concept: What Are Modules? Admin Wed, 05/01/2024 - 11:01

Module Development

11.0.x

Modules enable developers to customize Drupal without modifying the core software. To ensure a stable and upgradeable core system, Drupal defines integration points and patterns that developers can use to customize the system. Modules contain code (PHP, JavaScript, Twig, CSS, YAML, etc.) that can extend, alter, and enhance Drupal's features and functionality.

In this tutorial, you'll learn:

What Drupal modules are and their role in Drupal architecture
How modules interact with Drupal core to extend or alter site functionality
About the types of modules: core, contributed, and custom

By the end of this tutorial, you should be able to explain what modules are in Drupal, and understand their role in defining a Drupal site's functionality.

In this tutorial, you'll learn:

What Drupal modules are and their role in Drupal architecture
How modules interact with Drupal core to extend or alter site functionality
About the types of modules: core, contributed, and custom

By the end of this tutorial, you should be able to explain what modules are in Drupal, and understand their role in defining a Drupal site's functionality.

Goal

Define what modules are and their role in extending, altering, and enhancing Drupal.

Prerequisites

None.

What are modules in Drupal?

Modules are packages of code that use integration points or well-defined patterns to alter, extend, and enhance a Drupal site.

From an end-user perspective, modules add or change functionality of a Drupal site. Administrative users can install modules through Drupal's Extend administrative interface.

Learn more about how site builders use modules.

Each module has a specific purpose, ranging from feature enhancements to complex system integrations.

From a developer's perspective, modules are packages of code (mostly PHP) that extend Drupal to add new features or alter existing functionality. Modules can be installed to enable their features, and uninstalled to turn features off.

All modules are written in the same way and use the same patterns. Their exact implementation will vary depending on the intended use. A module intended for a specific project can take liberties and hard-code assumptions like a field's configuration options. A module intended for a global audience will need to be generic or configurable.

A module developer can contribute and maintain their modules as a project hosted on Drupal.org. These modules are available for others to download, use, and collaboratively improve. The ecosystem of contributed modules is a key part of why Drupal is successful.

Types of modules in Drupal

As a developer, you'll work with core, contributed, and custom modules.

Core modules

Modules included with Drupal core.
Live in the /core/modules directory.
Examples: Block, Comment, Field UI, Views

Core modules provide Drupal's primary feature set, and contain many of the APIs that you'll engage with as a module developer. You'll work with these when you want to implement one of the APIs, use one of the services they provide, fix a bug in Drupal core, or help contribute to an upstream feature.

Contributed modules

Modules downloaded from Drupal.org that are not part of Drupal core.
Typically placed in the /modules/contrib directory.
Examples: Admin Toolbar, Devel

Contributed modules are written to be generic and reusable. They are usually configurable with a settings form, and allow you to tailor their features to your specific use case. You'll work with these when you want to help fix a bug, maintain a module you've developed, and extend or alter a contributed module's features to meet the needs of your use case.

Learn more about contributing modules.

Work with the community to help maintain and improve contributed modules.

While not required, module contribution is an important part of the Drupal community ethos and a great way to learn.

Custom modules

Project-specific modules that you or another developer wrote specifically for your application.
Typically placed in the /modules/custom directory.

Custom modules are specific to a project and make application-specific tweaks to features provided by other modules. You'll work with these to define business-specific application logic. Custom modules are a place to create novel solutions that use APIs and integration points of existing core and contributed modules.

Common use cases for custom modules:

Site-specific SEO enhancements
Custom form processing and data validation rules
Integration with 3rd-party APIs, especially internal ones
Unique business logic
Custom reporting and analytics

Don't hack core!

The Drupal community follows the mantra, "Don't hack core". Following this principle ensures your Drupal site remains extensible and maintainable. If you alter code that is part of Drupal's core software, you will potentially face the following problems:

Loss of changes: Any modifications will be overwritten during core software updates, which can lead to loss of functionality.
Missing critical security updates: If you're unable or reluctant to perform core updates because of code modifications to the core software within a project, your site could miss critical security updates and become vulnerable to attack.
Compatibility issues: Custom changes might conflict with other subsystems or contributed modules, leading to unexpected behavior or errors.
Maintenance challenges: Custom changes to the core software make it difficult for other developers or even your future self to understand and maintain the site.

Read more about the "don't hack core" philosophy in this insightful Drupal Answers post.

What about bug fixes?

Bug fixes are regularly included in patch or minor updates to Drupal core and contributed modules. Which is why keeping your Drupal site up-to-date is important. But, the fact is that sometimes fixing a bug in Drupal core or a contributed module does require "hacking" code that doesn't belong to you. This can be true when a bug fix is available through a patch contributed to an issue, but the patch is not yet part of the official release. Perhaps a better mantra would be "don't hack core, but when you do, use a patch."

The Composer Patches plugin makes Composer an ideal tool for tracking, downloading, and applying these patches.

Learn more about patching projects using Composer.

Composer Configuration for Drupal: Patching core and contributed modules (Drupalize.Me)
Composer Patches plugin (GitHub.com)
Patching projects using Composer (Drupal.org)

Plugins, services, events, and hooks

Modules interact with the Drupal software through 4 primary patterns: plugins, services, events, and hooks. As a developer, these are the patterns that you'll need to learn to implement and apply in order to create custom modules.

Plugins: These are like the individual parts used to assemble a machine. They provide new features in a way that allows a Drupal administrator to choose one option from a list of many. For example, choosing specific blocks or field types when building your site makes the site unique.
Services: Think of services as specialized tools that can be swapped out. They handle specific tasks like sending emails or integrating with databases. You might have a drawer full of hammers, and they operate the same way, but you choose the right one depending on the job.
Events: These are like triggers that react to certain actions or conditions within Drupal, such as entity validation or dynamic routing.
Hooks: Hooks are like customizable attachment points in Drupal where you can "hook in" your own code to alter behavior or extend functionality.

In this guide, we'll explain and use each of these patterns as we develop custom modules for the Anytown Farmers Market site.

Recap

Modules are packages of code that use integration points or well-defined patterns to alter, extend, and enhance a Drupal site. Modules can be installed or uninstalled by administrative users to add or remove functionality. Core modules live in the core/modules directory and provide Drupal's primary features. Contributed modules typically live in modules/contrib and available for download on Drupal.org. Custom modules live in modules/custom, provide application-specific business logic, and integrate with other core and contributed modules. If you need to alter, enhance, or provide new features to a Drupal site, you should use modules instead of "hacking core". But, if you need to fix a bug, use Composer Patches if the fix is not yet part of an official release and a patch is available.

Further your understanding

Have you encountered modules (sometimes called plugins, or extensions) in other CMS platforms or frameworks?
Why would you want to be able to modify the way Drupal works without altering Drupal's code?

Additional resources

List of contributed modules (Drupal.org)
1.2. Concept: Modules (Drupal User Guide)
Chapter 11. Extending and Customizing Your Site (Drupal User Guide)
DrupalCon New Orleans 2016: Altering, Extending, and Enhancing Drupal 8 (YouTube.com)

May 2, 2024

Write a Unit Test

Admin — Fri, 26 Apr 2024 22:45:47 +0000

Write a Unit Test Admin Fri, 04/26/2024 - 17:45

Module Development

11.0.x

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.

September 30, 2024

Write a Kernel Test

Admin — Fri, 26 Apr 2024 22:45:47 +0000

Write a Kernel Test Admin Fri, 04/26/2024 - 17:45

Module Development

11.0.x

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.

October 18, 2024

11.0.x

Upgrade to Drupal 11

Goal

Prerequisites

Drupal 11 released August 2, 2024

Quickstart

Differences between Drupal 10 and Drupal 11

Notable 3rd-party dependency updates

Replace or uninstall deprecated core modules

Removed modules

When should I upgrade to Drupal 11?

Drupal 11 upgrade checklist

Update to Drupal 10.3.x (or later)

Update all your contributed projects

Use Upgrade Status module

Update your custom code

Verify your hosting meets the new requirements

Check the Upgrade Status report

Upgrade Drupal core

Update drupal/core-dev (if applicable)

Update drupal/core-* projects

Run composer update

Put your site in maintenance mode

Make a backup

Deploy your code

Check for and run database updates

Take your site out of maintenance mode

Celebrate! You've upgraded to Drupal 11!

Troubleshooting a Drupal 10 upgrade to Drupal 11

Problem: Permission denied updating files in sites/default/

Problem: Composer can't install packages

Problem: Contributed module only has a patch

Recap

Further your understanding

Additional resources

Implement a Plugin Using PHP Attributes

Implement a YAML Plugin

Implement a Plugin Using Annotations

PHP Attributes

Audience and Approach

Goal

Prerequisites

Audience

Approach

Learning objectives

Recap

Further your understanding

Additional resources

Guiding Scenario

Goal

Prerequisites

The guiding scenario

Weather forecast feature

Vendor attendance feature

Recap

Further your understanding

Additional resources

Concept: What Are Modules?

Goal

Prerequisites

What are modules in Drupal?

Types of modules in Drupal

Core modules

Contributed modules

Custom modules

Don't hack core!

What about bug fixes?

Plugins, services, events, and hooks

Recap

Further your understanding

Additional resources

Write a Unit Test

Write a Kernel Test

Update `drupal/core-dev` (if applicable)

Update `drupal/core-*` projects

Run `composer update`