- Getting Started: Configuring Drupal 11 to Apply Recipes
- .gitignore Configuration
- Preparing to Install Recipes
- Requiring and Applying Recipes
- From Packagist
- From a Git Repository
- From a local directory
- Applying a recipe
- recipe-apply Docksal Command Helper
- Using ddev exec command
- drupal DDEV Command Helper
- Unpacking a recipe
- recipe-unpack Docksal Command Helper
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
ddev exec
command
Using 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 "$@"