Getting Started: Configuring Drupal 11 to Apply Recipes¶

The following document describes the steps needed to configure a Composer based Drupal 10.3+ installation to be ready to apply Drupal recipes to.

Add the Drupal Recipe Unpack Composer Plugin (optional)¶

The https://github.com/woredeyonas/Drupal-Recipe-Unpack composer plugin can be run after you apply a recipe to add the package's from the recipe's composer.json file to your main project's composer.json file.

The plugin is not on Packagist, so you need to install the repository in your site's composer.json first.

{
    "type": "vcs",
    "url": "https://github.com/woredeyonas/Drupal-Recipe-Unpack.git"
}

When using Composer 2.2 or higher, Composer will ask for your permission to allow this plugin to execute code.

You can add the following lines to your site's composer.json file's config > allow-plugins section.

{
    "config": {
        "allow-plugins": {
            "ewcomposer/unpack": true,
        }
    }
}

Or run this command on the CLI:

composer config allow-plugins.ewcomposer/unpack true

.gitignore Configuration¶

Because we are installing recipes using composer, you will want to update your .gitignore file to exclude the path we added above to install recipes to:

/recipes

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

Verify that the composer.json and composer.lock files updated to include it.

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 your site's composer.json repositories section:

{
 "type": "vcs",
 "url": "https://gitlab.com/kevinquillen/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(s) under the repositories section using composer's path type:

{
 "type": "path",
 "url": "../path/to/recipes/folder/*"
}

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 unpack [organization/package-name]

After it completes, verify the packages have been added to the site's composer.json

`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 unpack "$@"