8.9.x/9.4.x

Install a Contributed Module with No Drupal 9 Release

Admin — Fri, 29 Oct 2021 18:44:32 +0000

Install a Contributed Module with No Drupal 9 Release Admin Fri, 10/29/2021 - 13:44

Site Building, Module Development, Backend and Infrastructure

8.9.x/9.4.x

As new major versions of Drupal are released, contributed modules need to be updated for compatibility. As of right now (October 2021) there are a lot of contributed modules with a Drupal 8 release and a patch in the queue to make them work with Drupal 9. However, there's no official Drupal 9 compatible release for the module, so the module can't be installed with Composer. This creates a circular problem where you can't composer require the module if you don't patch it, but you can't patch it until after it's been downloaded by Composer.

To help solve this common issue, Drupal.org provides a lenient Composer endpoint that publishes all modules as compatible with Drupal 9 regardless of whether that's true or not. By using it, you can composer require the module and then use cweagans/composer-patches to apply any necessary patches.

In this tutorial we'll:

Add the lenient Composer endpoint to our project's composer.json file
composer require a non-Drupal 9 compatible module
Use Composer to download and apply a patch that makes the module Drupal 9 compatible

By the end of this tutorial you should be able to use contributed modules that require a patch to be compatible with Drupal 9.

In this tutorial we'll:

Add the lenient Composer endpoint to our project's composer.json file
composer require a non-Drupal 9 compatible module
Use Composer to download and apply a patch that makes the module Drupal 9 compatible

By the end of this tutorial you should be able to use contributed modules that require a patch to be compatible with Drupal 9.

Goal

Use composer require to install a module that's not currently Drupal 9 compatible and then apply a patch so that it is.

Prerequisites

Use Composer with Your Drupal Project
The "Patching core and contributed packages" section of Composer Configuration for Drupal
This requires Composer >= version 2 to work

What is the lenient Composer endpoint?

Drupal.org publishes a second composer repository endpoint at https://packages.drupal.org/lenient. This endpoint advertises any module that DOES NOT have a core_version_requirement entry in the module's .info.yml file as being compatible with any version of Drupal. If a module already has a core_version_requirement entry in its .info.yml file then the endpoint doesn't publish the package.

Caveats

This requires Composer version 2 to work. Only Composer version 2 supports the priority repository feature that is being exploited to allow this to work. Composer 2 allows scanning through a list of repositories for a package starting with the first repository in the list and continuing through the list until it finds one with the requested package. Because the lenient endpoint only publishes modules that do not have a Drupal 9 release, as soon as the module is updated for Drupal 9 compatibility it'll be removed from the lenient endpoint and your project will use the official version.

Composer will output a warning message every time you use it while this lenient repository is present. Ideally, this is used as a stop-gap measure and all your projects have a full Drupal 9 release in the future.

Why add a lenient endpoint?

As of this writing (October 2021) Drupal 9 has been released, and Drupal 8 will reach end of life in November 2021. At that point, Drupal 8 sites will no longer receive security updates. In order to remain secure, all Drupal 8 sites should update to Drupal 9.

For many sites, this is difficult because the contributed modules they rely on do not yet have a Drupal 9 compatible release -- making updating difficult or impossible. Furthermore, in many cases the fixes required to make the Drupal 8 module compatible with Drupal 9 can be automated (there's already a bot that will generate patches when possible), or there is an existing patch in the issue queue that just hasn't been applied by the project's maintainers yet. But, without the lenient facade developers can't use Composer to apply these patches, in effect leaving them stranded on Drupal 8.

Use the lenient Composer facade

Ready to add the lenient Composer facade to your project and start making use of it?

Edit your composer.json file

Edit the existing composer.json file in the root of your project and update it so the "repositories" section looks like the following:

"repositories": {
    "lenient": {
        "type": "composer",
        "url": "https://packages.drupal.org/lenient"
    },
    "0": {
        "type": "composer",
        "url": "https://packages.drupal.org/8"
    }
},

It's important that https://packages.drupal.org/lenient is listed before https://packages.drupal.org/8 so that the repository priority feature works.

Composer require the Drupal 8 module

Now, you should be able to use composer to download the Drupal 8 compatible version of the module.

Example:

composer require drupal/consumers

Note: The drupal/consumers module is only used as an example and may already have a Drupal 9 compatible release.

Apply the Drupal 9 compatibility patch

The cweagans/composer-patches project can be used to apply patches automatically when running composer install or composer update.

First, make sure the package is present: composer require cweagans/composer-patches.

Then, edit the composer.json file in the root of the Drupal project (the same one you edited above) and add a "patches" section if it doesn't already exist.

Example:

{
  "extra": {
    "patches": {
      "drupal/consumers": {
        "[#3116338] Drupal 9 Compatibility": "https://www.drupal.org/files/issues/2020-03-10/3116338-composer-3.patch"
      }
    }
  }
}

Here, "drupal/consumers" is a list of patches to apply. Each one is a key/value pair. The key is a human-readable name and we recommend including the issue number so you can find it again later. The value is the path to the .patch file you want to apply.

Repeat for each module that needs patching.

At this point you should be able to use Composer to install modules for your Drupal 9 site, regardless of whether they advertise a Drupal 9 compatible release or not. However, this does not mean the modules work and you'll still need to test them out and perform your due diligence before deploying your updated site.

Recap

In order to make it easier to update sites to Drupal 9 before the Drupal 8 end of life is reached and sites running Drupal 8 no longer receive critical security updates, you can use the lenient Composer endpoint now on Drupal.org. The endpoint advertises a module as being compatible with Drupal 9 regardless of whether that's true or not. This endpoint allows Composer to require the module, download it, and apply any existing patches that make it actually Drupal 9 compatible. This is a stop-gap to help with upgrades, and both module users and maintainers should continue to work towards creating Drupal 9 compatible releases for the modules used by their projects.

Further your understanding

How does Composer's priority repository feature work?
What are some caveats of this approach to upgrading modules?
What can you do to help ensure the modules you are using get a stable Drupal 9 release?

Additional resources

Using Drupal's Lenient Composer Endpoint (Drupal.org)
See the Add a major-version-agnostic façade endpoint for stranded d8 projects issue for more details about how/why this was done. (Drupal.org)

February 22, 2023

Upgrade to Drupal 9

Admin — Mon, 01 Jun 2020 23:28:10 +0000

Upgrade to Drupal 9 Admin Mon, 06/01/2020 - 18:28

Backend and Infrastructure, Site Administration

8.9.x/9.4.x

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

In this tutorial we’ll:

Explain the differences between Drupal 8 and Drupal 9 that affect the upgrade path.
Walk through the high-level steps required to upgrade from Drupal 8 to Drupal 9.
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 8 and 9, audit your existing Drupal 8 projects for Drupal 9 readiness, estimate the level of effort involved, and start the process of upgrading.

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

In this tutorial we’ll:

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

Goal

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

Prerequisites

What Is Deprecated Code?

Differences between Drupal 8 and Drupal 9

From a technical perspective Drupal 9.0.0 is Drupal 8.9.0 with all the deprecated code removed. There are no significant schema changes, or feature additions, that would require a complex upgrade. As long as all the code in your project is using the current APIs the transition from Drupal 8.9.0 to Drupal 9.0.0 shouldn’t be any more complex than the move from 8.8.x to 8.9.0.

Credit: Gábor Hojtsy

Drupal 9 also includes major version updates to many of Drupal core’s dependencies, including Symfony and Twig. 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. This is less likely to impact you directly, but it’s good to be aware of this change.

Also, in Drupal 9, the Place Blocks and SimpleTest modules have been removed and replaced with Layout Builder and PHPUnit, respectively.

Since Drupal 9 is Drupal 8.9 with the deprecated code removed, a module that's not using any deprecated APIs, and has added the required content to its info file to declare that it's compatible with Drupal 9, should work with either major version. If you've used Drupal for a while this is new, and not how upgrades have worked in the past. But, it's so much better.

When should I upgrade to Drupal 9?

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 9 compatible. Once they are, there is no reason to not upgrade.

If you're using Drupal 8 you have until November 2021 to complete your upgrade. At that point, Drupal 8.9.x will be unsupported and Drupal 8 will have reached its end of life, which is also Symfony 3's end of life. Drupal 7 community support will be provided until January 5, 2025. Read more about Drupal 9's release date and what it means.

We like this article as a guide to figuring out when to upgrade: When to Upgrade from Drupal 8 to Drupal 9

Drupal 9 upgrade checklist

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

Update to Drupal 8.8.x or 8.9.x

Before you upgrade to Drupal 9 you need to be on the latest version of Drupal 8.

Learn how to perform a minor version update.

Update all your contributed projects

You should update all your contributed modules and themes to Drupal 9 compatible versions while you're still on Drupal 8.

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 9, you'll need to ensure that all of your contributed projects are already Drupal 9 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 9 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.

When you're ready to start working on the Drupal 9 readiness of the modules installed on your site, use the Upgrade Status on your current site to generate a report. And help fix some common issues. Learn more about using Upgrade Status.

If a module isn't Drupal 9 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 9-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 9. 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 9.

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 9 now you should start doing this. It'll save time in the future, and since Drupal 9 is backward-compatible with Drupal 8.9 it shouldn't affect your existing site.

Verify your hosting meets the new requirements

The hosting environment requirements for Drupal 9 have changed. You'll want to make sure your web server, PHP, and MySQL/MariaDB are all running compatible versions.

Upgrade Drupal core

These instructions assume you that your Drupal 8 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 an entries like "drupal/core-recommended": "^8.8", and "drupal/core-composer-scaffold": "^8.8" in your composer.json file. This is a good indication that you're using the current recommend approach.

You can learn more about making these changes in Update Drupal from Versions Prior to 8.8.x using Composer.

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. Alternatively, you can edit the version constraints in composer.json manually.

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

composer require drupal/core-dev:~9.0.0@dev --dev --no-update --update-with-dependencies

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

composer require drupal/core-recommended:~9.0.0@dev drupal/core-composer-scaffold:~9.0.0@dev --no-update --update-with-dependencies

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

composer update

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

  - Updating drupal/core-dev (8.8.7 => 9.0.0)

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

Troubleshooting a Drupal 9 upgrade

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 9 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.

If there's a -dev version of the module that you know is compatible with Drupal 9 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 9 compatible release will have a patch in the issue queue that makes the module work with Drupal 9, 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 9 compatible, so you need to apply a patch, but Composer can't apply the patch if it can't resolve the dependency tree first.

There is now an officially supported way to handle this using Composer. See Install a Contributed Module with No Drupal 9 Release.

Recap

In this tutorial we looked at what's involved in making the transition from Drupal 8 to Drupal 9. This included going over the differences between the two, auditing your custom and contributed modules for compatibility, learning how to make things Drupal 9 compatible while still using Drupal 8. 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 9 still requires a major migration. See our Learn to Migrate to Drupal guide.

Additional resources

Guide to Drupal 9 (Drupalize.Me)
Upgrading from Drupal 8 to Drupal 9 (or higher) (Drupal.org)
Preparing Your Drupal 8 Site for Drupal 9 (Lullabot.com)
Use Composer with Your Drupal Project (Drupalize.Me)
Troubleshoot Common Composer Issues (Drupalize.Me)

October 30, 2024

Update Drupal from Versions Prior to 8.8.x using Composer

Admin — Wed, 05 Feb 2020 22:02:46 +0000

Update Drupal from Versions Prior to 8.8.x using Composer Admin Wed, 02/05/2020 - 16:02

Site Administration

8.9.x/9.4.x

Drupal 8.8.0 introduced a bunch of new features intended to make it easier over the long-term to maintain a Drupal project using Composer. In doing so it establishes some new best practices, and moves into Drupal core solutions that were previously maintained by the community. This is all good news. But, it means if you're using Composer to update from Drupal 8.7.x or lower to 8.8.0 or higher you'll need to do a bit of additional work to untangle everything.

This tutorial is especially useful if you started your Drupal project using the drupal-composer/drupal-project template and would like to convert to use the new templates (i.e. drupal/recommended-project or drupal/legacy-project) included with Drupal 8.8.x core.

In this tutorial we'll:

Convert our project to use the new drupal/core-recommended, and drupal/core-dev Composer packages
Explain which commonly used Composer packages are deprecated, and which new ones replace them
Learn how to use the drupal/core-composer-scaffold Composer plugin
Cover tips for troubleshooting updates

Furthermore, in order to Upgrade to Drupal 9 from Drupal 8, you will first need to update your Drupal 8 site to at least version 8.8, as the upgrade paths for Drupal 8 site from before Drupal 8.8.0 have been removed from Drupal 9.

By the end of this tutorial you should be able to update your Drupal projects using Drupal core 8.7.x or lower to Drupal core 8.8.0 or higher using Composer. And be ready for an upgrade to Drupal 9.

In this tutorial we'll:

Convert our project to use the new drupal/core-recommended, and drupal/core-dev Composer packages
Explain which commonly used Composer packages are deprecated, and which new ones replace them
Learn how to use the drupal/core-composer-scaffold Composer plugin
Cover tips for troubleshooting updates

By the end of this tutorial you should be able to update your Drupal projects using Drupal core 8.7.x or lower to Drupal core 8.8.0 or higher using Composer. And be ready for an upgrade to Drupal 9.

Goal

Update from an older version of Drupal core to Drupal 8.8.0 or later using Composer.

Prerequisites

If you're following this tutorial, we assume you're already using Composer to manage your Drupal site dependencies. But if you're looking for a general introduction to Composer, we recommend The Wonderful World of Composer.

Before you get started

You probably won't need to do all of these steps, and some of them may not be exactly right for your use-case, but we'll do our best to explain what's changing and why so that hopefully you can get it all working.

We recommend reading through this whole tutorial first and determining which elements apply to you before proceeding with updating.

Prior to Drupal 8.8.0 many sites used the drupal-composer/drupal-project as the basis for their projects. If you did, there are some additional steps you'll need to take to update to Drupal 8.8.0 or higher.

Why do I need to do this?

Previously, the recommended way to install Drupal with Composer was the following command:

composer create-project drupal-composer/drupal-project:8.x-dev some-dir --no-interaction

Note: You can still use drupal-composer/drupal-project for starting a new project. It's already been updated with to reflect these changes. Learn more about installing Drupal with Composer.

What the command above does is download all the files in the drupal-composer/drupal-project repository and then run composer install. You've now got a starting point for your project, but there is no link to the original template. From here on out all of those files are your responsibility. The idea is to provide some scaffolding for common configuration that most any Drupal project would want. And to save you a few keystrokes every time you start a new project.

The drupal-composer/drupal-project template made use of some packages that are now deprecated in favor of new ones that are provided by Drupal core. And as part of updating to Drupal 8.8.0+ you'll want to switch from using these now deprecated packages to the new recommended ones.

Since your project is no longer connected to the upstream template, you'll need to make these changes yourself.

Note: Running many of the commands included below can impact the code that's installed for your project, and can have unintended consequences. It's a good idea to make a backup before trying any of these. And to test on a development environment first.

Use the drupal/core-recommended meta package

When installing Drupal core with Composer you should require drupal/core-recommended instead of drupal/core. Recommended in this case means that this specific version of Drupal core and these specific versions of its dependencies have passed all the automated tests and are deemed suitable for release.

It's possible, though rare, that if you use different versions of one of Drupal core's dependencies than the one that was tested for the release that there might be bugs. By using drupal/core-recommended you can prevent dependency versions from drifting upwards, and ensure that you always get the same dependencies that were used in the release. You can be more confident when deploying your application knowing that the combination of core and dependencies is verified to work.

Prior to Drupal 8.8.0 the drupal/core-recommended package did not exist and many Drupal sites used the webflo/drupal-core-strict meta package which locked dependencies to exact versions. For example, it might use drupal/core: "8.8.1" instead of drupal/core: "^8.8". The former would only ever resolve to 8.8.1 while the later might resolve to 8.8.1 or 8.8.0.

As of Drupal 8.8.0 using the drupal/core-recommended meta package provides this dependency locking and webflow/drupal-core-strict is no longer necessary.

Caveat: It's possible (though rare) that a contributed module might explicitly require a different version of a Symfony component than the one that is pinned in your current version of drupal/core-recommended. If that's the case you can still use drupal/core which has a more lenient set of dependency version constraints.

Our rule of thumb: if it works for your set of required contributed modules and other Composer packages, use drupal/core-recommended and enjoy the extra confidence. But if it doesn't, use drupal/core. That's why the package is named recommended and not required.

Switch to `drupal/core-recommended`

If your existing composer.json contains a record for drupal/core replace it with drupal/core-recommended: "^8.8".

The following commands will convert from drupal/core to drupal/core-recommended. These commands will modify your composer.json file, but not remove, or download, any code because of the --no-update flag:

composer remove drupal/core --no-update
composer require composer/installers:^1.7 --no-update
composer require drupal/core-recommended:^8.8 --no-update

You can also edit the composer.json file manually instead of using the command above.

Important caveat: If Drupal is installed in the root directory of your project, and not in a subdirectory like web/ (is the Drupal core/ directory in the root of your project?) you should refer to the drupal/legacy-project template instead. The latter assumes the current best practice of using a web/ subdirectory.

To use the drupal/legacy-project template, you will also need to require drupal/core-vendor-hardening: "^8.8". So the Composer commands to update your requirements to match the drupal/legacy-project template would be:

composer remove drupal/core --no-update
composer require composer/installers:^1.7 --no-update
composer require drupal/core-recommended:^8.8 --no-update
composer require drupal/core-vendor-hardening: ^8.8 --no-update

If you're migrating from webflo/drupal-core-strict, to drupal/core-recommended you need to remove your project's dependency on the legacy package. You can do so with the following composer command:

composer remove webflo/drupal-core-strict --no-update

Use the drupal/core-dev meta package

The drupal/core-dev package contains all the optional development specific core dependencies. For example, the code required to run automated tests. This package can either be left out, or added to the "require-dev" section of your composer.json file as they're only needed for development.

This package replaces webflo/drupal-core-require-dev if you were previously using that you can remove it with:

composer remove webflo/drupal-core-require-dev --dev --no-update

And then add the new one:

composer require drupal/core-dev:^8.8 --no-update

Dealing with scaffolding

There are certain files in every Drupal install that are required for the project to work, but don't necessarily always have to live in the same place. Files like index.php and .htaccess for example. And optional example files like .editorconfig, .gitignore, sites/example.settings.local.php that are included with the project to serve as an example, but might need to be placed in a different location depending on the specific structure of your codebase. These are known as scaffold files.

And you need to teach Composer where to put them.

This is accomplished using the drupal/core-composer-scaffold Composer plugin. Which, replaces the drupal-composer/drupal-scaffold package if you were using it.

If you were using drupal-composer/drupal-scaffold, first remove the requirement:

composer remove drupal-composer/drupal-scaffold --no-update

Add the new core scaffolding plugin:

composer require drupal/core-composer-scaffold:^8.8 --no-update

And then configure it by editing your composer.json file to include the necessary configuration in the "extra" section:

"extra": {
  "drupal-scaffold": {
      "locations": {
          "web-root": "web/"
      }
  },
}

The web-root key allows you configure which directory contains the Drupal core installation. And will result in for example web/index.php and web/.htaccess. If you use a different sub-directory like docroot/ you can change that here.

Sometimes you might want to make changes to scaffold files, and use your modified version instead of the default. This is accomplished by copying the file you want to change into its normal location. Committing the changed version. And then configuring the plugin to stop replacing that particular file.

Learn more about additional configuration options for drupal/core-composer-scaffold.

Run `composer update`

After making all the necessary changes to your composer.json file you'll run composer update to get all the correct files and most importantly update your composer.lock file.

If you want to update only the required files and not also update things like contributed modules at the same time use composer update --lock.

Update settings.php

As of Drupal 8.8.0 the configuration sync directory is now defined as $settings['config_sync_directory'] instead of $config_directories. (Change record). This setting is used to tell Drupal where the configuration files for your site are stored on disk. And needs to be updated if it's used.

Open your settings.php file and change:

$config_directories['sync'] = 'my/config/dir';

To:

$settings['config_sync_directory'] = 'my/config/dir';

You may also need to update the configuration for the temporary files directory. Also in settings.php, change:

$config['system.file']['path']['temporary'] = 'my/temp/dir';

To:

$settings['file_temp_path'] = 'my/temp/dir';

Run database updates

At this point you should have the code for your project up-to-date, and you'll need to run the database updates. This process is the same regardless of what version you're updating from. See Update Drupal's Minor Version for more information.

Troubleshooting

The update process will likely vary a bit for everyone as a lot depends on changes that you made to your Drupal installation after the initial setup. Below are some useful tips if you're running into issues.

Compare your composer.json to the one from the new drupal/recommended-project template which can be found here https://github.com/drupal/recommended-project/blob/8.8.x/composer.json.

If running composer install, or composer update is resulting in an uninstallable set of dependencies you can try the nuclear option:

rm composer.lock
rm -r vendor/
composer install

This can result in unintended updates. For example contributed modules that you installed will all be updated to the latest version allowed by composer.json which may differ from the version currently installed via composer.lock.

You can also use composer prohibits drupal/core:8.8.0 to learn more about what is preventing the update from resolving to a useable set of dependencies.

If you're experiencing permissions issues see this tip in the documentation.

Recap

In order to update to Drupal core 8.8.x from previous versions you might need to replace some new deprecated Composer packages with the new community supported ones. This especially if you started out using the drupal-composer/drupal-project Composer template. Doing so requires updating your composer.json file with some new dependencies and new configuration. Then testing it all to make sure it still results in a usable set of dependencies.

Further your understanding

Does your project have customizations to scaffold files like .htaccess or robots.txt? Take some time to read about using the scaffold plugins configuration to make it easier to maintain these changes going forward.
While you're at it it's not a bad idea to update and test the contributed modules your site uses.
Upgrade to Drupal 9.

Additional resources

Change record: Upgrade paths for Drupal 8 site from before Drupal 8.8.0 have been removed from Drupal 9 (drupal.org/list-changes)
Update Core via Composer (Drupal.org)
Guide to the Drupal 8.8 Update (palantir.net)
Updating to Drupal 8.8.0 Beta with Composer (previousnext.com)

March 30, 2022

Run Drupal in Docker

Admin — Wed, 10 Jan 2018 14:00:00 +0000

Run Drupal in Docker Admin Wed, 01/10/2018 - 08:00

Backend and Infrastructure

8.9.x/9.4.x

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.

July 28, 2023

Custom tutorial icon

Core Themes: Stark

Admin — Thu, 30 Mar 2017 13:00:02 +0000

Core Themes: Stark Admin Thu, 03/30/2017 - 08:00

Theming

8.9.x/9.4.x

Stark is one of the themes bundled with Drupal. It is intentionally bare bones and its purpose is to help Drupal theme and module developers get to the heart of Drupal's system templates. In this tutorial, we'll explore Stark and its primary features and discuss the various reasons for utilizing the Stark theme.

Goal

Recognize Stark theme and identify its primary features. Explain the use cases for Stark and what you can learn from it.

Prerequisites

What Is a Theme?

Watch Core Theme: Stark

Why explore Stark?

Examine the default markup and behavior provided by the Drupal system.
Troubleshoot Drupal core behavior and output.
Troubleshoot and isolate problems from other modules or themes.

According to Stark's README.txt, Stark is provided for demonstration purposes. As it applies no styling through CSS, what Stark demonstrates is Drupal's default markup, as defined in core system templates. Stark overrides nothing; it even sets the base theme to false so that you can truly get down to the bare bones default markup of Drupal's system templates and see the result.

Stark can help you learn and identify Drupal's system templates and markup. This demonstration theme will serve you best if you first set up your local environment for theme development. Once done, use browser tools to inspect elements or view source to see which of Drupal's system templates are in use for various elements. Part of truly mastering theming in Drupal is understanding what components you already have available to you, and this certainly includes Drupal's system templates.

For troubleshooting, switching to Stark temporarily can help you determine whether problematic CSS or JavaScript coming from a module or complex theme is to blame.

Stark does include a few files that are there but don't actually do anything, except to show you that you could use them.

Stark's css/layout.css exists, but is now blank (see Issue #2349711). It's blank so that Stark is truly "stark" now and truly allows you to see Drupal's default output with a browser's default styling.
To the same purpose and in the same issue, (#2349711), Stark no longer removes normalize.css, a file is added by core. By keeping it, or rather by doing nothing to remove it as it did before, Stark remains a theme that can be used to examine and troubleshoot Drupal core's default behavior, which includes the addition of normalize.css.
Stark's stark.libraries.yml exists to show you how to load a CSS library, and it does in fact add css/layout.css to the head of the HTML pages that use Stark, it just doesn't do anything to the layout, because layout.css is blank.
Similarly, stark.breakpoints.yml does include some good examples of breakpoints, but since they don't correspond to any actual media queries in a CSS file in the Stark theme, this file doesn't really represent any real breakpoints or media queries in Stark. (See What Is a Breakpoint YAML File? to learn more about the purpose of a THEME-OR-MODULE.breakpoints.yml file).

Recap

In this tutorial, we explored Stark, a core Drupal theme. We learned what the purpose of Stark is and why it can be useful to enable and use Stark, especially when you want to learn about Drupal's system template files or need to troubleshoot certain problems with your Drupal site.

Further your understanding

Explain two use cases for utilizing Stark to a colleague.
What is the core system template for the main menu?
Describe a troubleshooting situation in which enabling Stark might be useful.

Additional resources

Configure Your Local Environment for Theme Development (Drupalize.Me)

February 11, 2021

Core Themes: Bartik

Admin — Thu, 30 Mar 2017 13:00:02 +0000

Core Themes: Bartik Admin Thu, 03/30/2017 - 08:00

Theming

8.9.x/9.4.x

Bartik is a core theme in Drupal. As a default theme for Drupal, it serves as an instructive example of a well-developed responsive theme. In this tutorial, we'll tour and explore Bartik, identify its primary features, and explain the use case for the Bartik theme and what you can learn from it.

Goal

Recognize Bartik theme and identify its primary features. Explain the use cases for Bartik and what you can learn from it.

Prerequisites

What Is a Theme?

Watch Core Theme: Bartik

Why explore Bartik?

It's a good example of how to create a custom theme.
See the principles of Drupal theming-in-action.
It's Drupal's default theme and the first theme you'll see when you install Drupal.
See how Drupal implements responsive features in a theme.

Explore the files of Bartik

To get familiar with Bartik and the principles of Drupal theming, fire up a text editor and start exploring the files inside the Bartik theme.

Navigate to core/themes/bartik

This is the root directory for the Bartik theme.

Explore Bartik's info file

Open bartik.info.yml in a text editor or IDE such as PhpStorm. Here you'll find examples of how a theme can define meta information, indicate a base theme, attach libraries, specify stylesheets for CKEditor, and define regions.

Explore Bartik's template files

Navigate to the templates directory and explore Bartik's template files. You might want to start with page.html.twig and notice how Bartik's regions, defined in bartik.info.yml, are output via the page array using Twig.

Explore Bartik's CSS libraries

Take a look at bartik.libraries.yml and notice how all of Bartik's CSS files in its css directory are listed here under the global-styling key. To learn about the concept of libraries in Drupal theming and how to define and attach libraries, check out the following tutorials:

Explore preprocess functions in bartik.theme

Open bartik.theme. This is a PHP file (known in previous versions of Drupal as template.php) containing PHP functions, mostly preprocess hooks. In Bartik's ".theme" file, you'll find functions that implement a variety of preprocess hooks, altering and adding variables to various template files. To learn more about preprocess functions, explore the following tutorials and use Bartik as an example to follow along:

Explore Bartik's responsive features

Open bartik.breakpoints.yml and take note of the breakpoints defined in this YAML file.
Navigate to the Extend page and enable the core Responsive Images module.
Navigate to Configuration > Responsive Image styles
Under Breakpoint group, select Bartik. Notice how the breakpoints defined in bartik.breakpoints.yml correspond with those listed in the field sets now displayed under Breakpoint group.

To learn more about breakpoint configuration files, see this tutorial: What Is a Breakpoint YAML File?

Explore Bartik's integration with Color module

Navigate to Appearance > Settings > Bartik
Notice that Bartik's settings include a color picker UI
Try it out and change the background colors of the header
In a code editor, navigate to core/themes/bartik/color and explore the files inside: color.inc, preview.css, preview.html, and preview.js.
See also the documentation for Color module on Drupal.org

As you can see, there's a lot to learn just by exploring Bartik. Use our theming guide in conjunction with Bartik to explore many principles of Drupal theming in action, and then apply what you learn in your own custom theme.

If you want to use Bartik's files and structure as a basis for your own theme, don't modify core/themes/bartik, but instead copy core/themes/bartik to themes/ and rename the directory and any filename containing the "bartik" with your new theme's machine name. See the tutorial Structure of a Theme for more details on how to set up a custom theme. These same guidelines apply to any theme, including the next core theme we'll be exploring: Stark.

Recap

In this tutorial, we explored Bartik, a core theme in Drupal. We learned about Bartik's unique features and what theming concepts you can learn from exploring Bartik's theme files.

Further your understanding

Explain to a colleague two or three reasons why it can be useful and instructive to explore Bartik.
Which Drupal module does Bartik depend on in its theme settings?
What is the name of the file that defines Bartik's regions?

Additional resources

This sampling of resources will help you understand Bartik and learn the concepts and techniques of theming in Drupal. Explore other theming tutorials in the rest of our Drupal Theming Guide.

Drupal Base Themes: Stable and Classy (Drupalize.Me)
Install and Uninstall a Theme (Drupalize.Me)
Structure of a Theme (Drupalize.Me)
Describe Your Theme with an Info File (Drupalize.Me)
Regions (Drupalize.Me)
Theme Inheritance with Base Themes (Drupalize.Me)
Breakpoints in Drupal (Drupalize.Me)
Twig in Drupal (Drupalize.Me)
What Are Libraries? (Drupalize.Me)
Documentation for Color module (Drupal.org)

February 11, 2021

Drupal Console

Admin — Thu, 06 Oct 2016 22:18:11 +0000

Drupal Console Admin Thu, 10/06/2016 - 17:18

Backend and Infrastructure

8.9.x/9.4.x

The Drupal Console is a suite of tools run from a command line interface (CLI) to generate boilerplate code and interact with a Drupal installation.

Note: This project is no longer actively maintained. See the Drush topic for alternative solutions.

The Drupal Console is a suite of tools run from a command line interface (CLI) to generate boilerplate code and interact with a Drupal installation.

Note: This project is no longer actively maintained. See the Drush topic for alternative solutions.

Goal

Learn about the Drupal Console and what you can do with it.

Prerequisites

Installing Drupal Console

To get up and running with Drupal Console, follow the instructions in the project's official documentation: Getting the project.

Tip: If you're running into difficulty installing Drupal Console with an existing site (and dependencies are not resolving), try passing the --no-update flag, which will disable automatic updates of dependencies.

composer require drupal/console:~1.0 \
--prefer-dist \
--optimize-autoloader \
--sort-packages \
--no-update

composer update

What does Drupal Console do?

For a complete list of commands run drupal list, or view the documentation.

Generate code

Drupal Console provides a number of commands for creating module scaffolding and boilerplate code. Generation commands will walk you through a set of interactive questions about what you want to generate. Then it will generate the required boilerplate to build the requested component. This can dramatically decrease the time it takes to write common components like plugins, services, or custom entity types.

Note: When using Drupal Console to generate a module or theme, you will need to edit the info file and add the core_version_requirement key. For details, see Overview: Info Files for Drupal Modules and Describe Your Theme with an Info File.

Try out various Drupal Console's code scaffolding commands in the following tutorials:

Interact with your Drupal installation

Drupal Console allows you to interact with your Drupal installation, from rebuilding caches, to listing routes, services, and modules, and interacting with the configuration management.

One of our favorite features is that Drupal Console will create lists of things like plugin types, events, and services available. Because it's being used in the context of your specific installation, that list will include options provided by any contributed modules not just Drupal core. This means the documentation provided by Drupal Console in the context of your site will be a bit more complete than what you might find online.

Learn to develop with Drupal

Drupal Console helps you learn to develop applications with Drupal. In addition to generating complex code, you can increase the verbosity of the code comments, to better understand the generated code and how to build on it, by using the --learning option.

You can also use Drupal Console to explore the inner workings of your current installation using the debug:* commands.

Recap

In this tutorial, we learned about some things you can do in a Drupal project with the command-line interface tool, Drupal Console.

Further your understanding

Browse through the available commands and see if there's one that you could try out right now.
Learn about the latest version of Drush. While it doesn't provide all of the features of Drupal Console, there is a lot of overlap.

Additional resources

Official project page http://drupalconsole.com, and documentation
Learn Drush: The Drupal Shell (Drupalize.Me)

July 12, 2024

Alternate resources

Some (not all) features of Drupal Console are available in Drush. See Install Drush Using Composer.

Underscore.js in a Theme or Module

Admin — Wed, 30 Mar 2016 13:00:00 +0000

Underscore.js in a Theme or Module Admin Wed, 03/30/2016 - 08:00

Theming

8.9.x/9.4.x

Underscore.js is a very small library which provides several utility functions and helpers to make working with JavaScript a little bit easier. In this tutorial we'll take a look at a part of the library, learn where the full library is documented, and see how we can make use of Underscore.js in a custom block on our Drupal site.

January 26, 2023

Alternate resources

See the related change record for information on how to update your Underscore code with vanilla JS.

Use a Base Theme

Admin — Wed, 24 Feb 2016 14:00:00 +0000

Use a Base Theme Admin Wed, 02/24/2016 - 08:00

Theming

8.9.x/9.4.x

Make your theme a subtheme of a base theme, allowing it to inherit all the base theme's templates and other properties. When creating Drupal themes it is common to use the Classy theme provided with Drupal core as a base theme to jumpstart your development.

In this tutorial we'll learn how to:

Use the base theme key in our theme's THEMENAME.info.yml file
Make our Ice Cream theme inherit from the Classy theme, or any other theme

By the end of this tutorial you should be able to tell Drupal that your theme is a child of another theme and should inherit all of the parent theme's features.

August 13, 2024

Drupal Base Themes: Stable and Classy

Admin — Wed, 24 Feb 2016 14:00:00 +0000

Drupal Base Themes: Stable and Classy Admin Wed, 02/24/2016 - 08:00

Theming

8.9.x/9.4.x

Drupal core comes with a few base themes: Stable, Stable 9, Classy, and Stark. Each one has a different intended use case. And all of them are useful as a reference for building your own themes.

In this tutorial we'll:

Learn what each of the base themes included in Drupal core is intended to be used for
Compare the output from the base themes with a focus on Stable and Classy

By the end of this tutorial you'll be able to explain the use case for each of the base themes included with Drupal core and make an informed decision about which, if any, to use when creating your own custom themes.

February 23, 2022

Alternate resources

Stable and Classy have been removed from core. For new themes, see Start a New Theme with Starterkit. To update a theme's dependency on stable or classy, see the following change records on Drupal.org:

8.9.x/9.4.x

Install a Contributed Module with No Drupal 9 Release

Goal

Prerequisites

What is the lenient Composer endpoint?

Caveats

Why add a lenient endpoint?

Use the lenient Composer facade

Edit your composer.json file

Composer require the Drupal 8 module

Apply the Drupal 9 compatibility patch

Recap

Further your understanding

Additional resources

Upgrade to Drupal 9

Goal

Prerequisites

Differences between Drupal 8 and Drupal 9

When should I upgrade to Drupal 9?

Drupal 9 upgrade checklist

Update to Drupal 8.8.x or 8.9.x

Update all your contributed projects

Update your custom code

Verify your hosting meets the new requirements

Upgrade Drupal core

Troubleshooting a Drupal 9 upgrade

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

Update Drupal from Versions Prior to 8.8.x using Composer

Goal

Prerequisites

Before you get started

Why do I need to do this?

Use the drupal/core-recommended meta package

Switch to drupal/core-recommended

Use the drupal/core-dev meta package

Dealing with scaffolding

Run composer update

Update settings.php

Run database updates

Troubleshooting

Recap

Further your understanding

Additional resources

Run Drupal in Docker

Core Themes: Stark

Goal

Prerequisites

Watch Core Theme: Stark

Why explore Stark?

Recap

Further your understanding

Additional resources

Core Themes: Bartik

Goal

Prerequisites

Watch Core Theme: Bartik

Why explore Bartik?

Explore the files of Bartik

Navigate to core/themes/bartik

Explore Bartik's info file

Explore Bartik's template files

Explore Bartik's CSS libraries

Explore preprocess functions in bartik.theme

Explore Bartik's responsive features

Explore Bartik's integration with Color module

Recap

Further your understanding

Additional resources

Drupal Console

Goal

Prerequisites

Installing Drupal Console

What does Drupal Console do?

Generate code

Interact with your Drupal installation

Switch to `drupal/core-recommended`

Run `composer update`