Getting Started: Configuring Drupal 11 to Apply Recipes¶

This document describes the steps needed to configure a Composer-based Drupal 10.3+ installation to be ready to apply Drupal recipes to. If you started your project on Drupal 11.2 or later (which includes Drupal CMS 1.2.0 or later), this is already done for you!

If you started on an older version of Drupal, run the following commands in your project root (where composer.json is located).

# Tell Composer to allow the `drupal/core-recipe-unpack` plugin to run.
composer config allow-plugins.drupal/core-recipe-unpack true

# Install the plugin. It will work on any version of Drupal.
composer require drupal/core-recipe-unpack

# Ensure that your version of `composer/installers` is up to date:
composer require composer/installers:^2.3

# Finally, ensure that recipes install in the `recipes` directory. Note that the quoting is important in this command, and it should look exactly like the following.
composer config --merge --json extra.installer-paths '{"recipes/{$name}":["type:drupal-recipe"]}'

You are now ready to download and apply recipes!

.gitignore Configuration¶

Recipes aren't meant to be committed to your code repository, but rather to be applied to your site, then removed. Therefore, it's considered good practice to add the recipes directory to your gitignore file:

echo '/recipes' >> .gitignore

Preparing to Install Recipes¶

Successfully installing a recipe requires the site be installed. For minimal configuration collisions it may be optimal to use the minimal install profile while testing.

Requiring and Applying Recipes¶

From Packagist¶

If the recipe package is available from packagist, you will only need to require it.

composer require kanopi/gin-admin-experience

From a Git Repository¶

If the recipe package is in a public repository not available on Packagist, first you need to add the location to composer.json's repostories:

composer config repo.SOME_NAME vcs https://gitlab.com/kevinquillen/drupal-base

You can replace SOME_NAME with any short name you want (for example, drupal-base).

Then require the package:

composer require kevinquillen/drupal-base

From a local directory¶

Recipe packages that are locally stored should still be installed using Composer, especially if the recipe contains additional dependencies. First, your recipe should have a composer.json file. Then, your site's composer.json should include the path to your recipe under the repositories section, using Composer's path type:

composer config repo.SOME_NAME path ../path/to/recipe/folder

As with the previous example, you can replace SOME_NAME with any short name you want (for example, my-local-recipe).

Then require the package using the name (and version, if applicable) specified in the recipe's composer.json file.

Applying a recipe¶

Recipes are applied using core's PHP drupal script. In your CLI, CD into your webroot (traditionally /web or /docroot depending on host), and run the following command:

php core/scripts/drupal recipe ../recipes/[recipe-name]

Run drush cr to clear the cache, and verify on your site that the changes from the recipe were applied.

Follow your normal Git workflow to commit the changes.

`recipe-apply` Docksal Command Helper¶

Here is a Docksal command called recipe-apply that makes it a bit easier by cd-ing into the webroot, applying the recipe, and rebuilding the cache. This could be adapted to DDEV and Lando also.

#!/usr/bin/env bash

#: exec_target = cli

## Apply a Drupal Recipe that has been installed using Composer.
##
## Usage: fin recipe-apply [name]
##

# Abort if anything fails
set -e

DOCROOT_PATH="${PROJECT_ROOT}/${DOCROOT}"

cd ${DOCROOT_PATH}

php core/scripts/drupal recipe ../recipes/"$@"

drush cr

Using `ddev exec` command¶

You can use ddev exec to apply a recipe by specifying the path to the webroot (web, docroot, etc) like the following:

ddev exec -d /var/www/html/[web-root] php core/scripts/drupal recipe ../recipes/[recipe-name]

`drupal` DDEV Command Helper¶

Here is a DDEV command called drupal that gives easier access to the drupal script within your DDEV web container. To use, add a file called drupal with the following contents to either your global or project .ddev/commands/web/ directory. Now you'll be able to run a command like ddev drupal recipe ../recipes/[recipe-name] in your project.

#!/bin/bash

## Description: run the Drupal core script with provided arguments
## Usage: drupal <arguments>
## Example: ddev drupal recipe recipes/drupal-base

cd ${DDEV_DOCROOT}

php core/scripts/drupal "$@"

Unpacking a recipe¶

To "unpack", or move the recipe's package requirements to the site's composer.json, run the following command:

composer recipe-unpack [organization/package-name]`

After it completes, double-check that the packages have been added to the site's composer.json. In most cases, recipes are automatically unpacked when you require them, so you shouldn't need to run this command very often.

`recipe-unpack` Docksal Command Helper¶

Here is a Docksal command called recipe-unpack that makes it a bit easier. This could be adapted to DDEV and Lando also.

#!/usr/bin/env bash

#: exec_target = cli

## Unpack a Drupal Recipe to the site's composer.json
##
## Usage: fin recipe-unpack [organization/package-name]
##

# Abort if anything fails
set -e

composer recipe-unpack "$@"