Drainpipe

Drainpipe is a composer package which provides build tool and testing helpers for a Drupal site, including:

• Site and database updates
• Artifact packaging for deployment to a hosting provider
• Automated testing setup
• Integration with DDEV
• CI integration

Installation

composer config extra.drupal-scaffold.gitignore true
composer config --json extra.drupal-scaffold.allowed-packages "[\"lullabot/drainpipe\", \"lullabot/drainpipe-dev\"]"
composer require lullabot/drainpipe
composer require lullabot/drainpipe-dev --dev

and if using DDEV, restart to enable the added features:

ddev restart

Taskfile

Drainpipe will scaffold out various files, most importantly a Taskfile.yml in the root of your repository. Task is a task runner / build tool that aims to be simpler and easier to use than, for example, GNU Make. Since it's written in Go, Task is just a single binary and has no other dependencies. It's also cross-platform with everything running through the same shell interpreter.

Drainpipe installs the Task binary for you, no matter if you are using DDEV or not. If you already have Task installed system-wide and are not using DDEV, your installed binary will be linked from the vendor/bin directory.

You can see which tasks are available after installation by running ./vendor/bin/task --list or ddev task --list if you're running DDEV. To get more information on a specific task e.g. what parameters it takes, you can run task [task name] --summary.

Your Taskfile.yml can be validated with JSON Schema:

curl -O https://taskfile.dev/schema.json
npx ajv-cli validate -s schema.json -d scaffold/Taskfile.yml

See .github/workflows/ValidateTaskfile.yml for an example of this in use.

Overriding files provided by drainpipe

Drupal scaffolds are core files automatically placed and updated in the project root by drupal/core-composer-scaffold (documentation).

Scaffold files provided by Drainpipe are located in the main scaffold directory, while Nightwatch specific scaffold files can be found in drainpipe-dev/scaffold.

To determine where a file is placed, edit the extra.drupal-scaffold section in composer.json. Check how each scaffolded file defined in /src/ScaffoldInstallerPlugin.php for Drainpipe provided files, and drainpipe-dev/src/NightwatchScaffoldPlugin.php for Nightwatch specific files.

A specific file scaffolding can be disabled by mapping it to false under the extra.drupal-scaffold.file-mapping in the project composer.json file. This prevents it from being created or overriden when running composer install or composer update. Note Drainpipe workflows cannot be overridden.

{
  "extra": {
    "drupal-scaffold": {
      "file-mapping": {
        "[web-root]/robots.txt": false
      }
    }
  }
}

Binaries

If you receive an error such as exec format error: ./vendor/bin/task, then you may have the wrong binary for your architecture. If your architecture wasn't detected correctly, please open an issue with the output of php -r "echo php_uname('m');", along with information on your hardware and operating system.

You can override the platform and processor with environment variables DRAINPIPE_PLATFORM and DRAINPIPE_PROCESSOR. Valid platform values are linux, darwin, or windows, and processors are 386, amd64, or arm64. These correspond to builds of upstream dependencies e.g. https://github.com/go-task/task/releases

Tugboat

The Tugboat configuration file is not a static file; it is dynamically generated based on your .ddev/config.yaml file. To see the implementation details, check /src/TugboatConfigPlugin.php.

Node JS

All Drainpipe components (DDEV, Github Actions, Tugboat) are configured to use the same Node JS major version. This is set in the .nvmrc file, which is scaffolded from the Drainpipe's root directory, but can be overriden to use a different Node version.

Renovate Presets

If you are using Renovate (for automated dependency updates) you can use/extend our Drupal presets by doing the following:

{
  "extends": [
    "group:drupal-core"
 ]
}

This preset provides safe automation with flexibility and control for teams maintaining Drupal applications, minimizing risk by requiring approval for major changes while accelerating security patches through the automerging of minor updates.

Database Updates

The drupal:update command follows the same procedure as the 'drush deploy' command, with the exception that it runs the configuration import twice as in some cases the import can fail due to memory exhaustion before completion.

drush updatedb --no-cache-clear
drush cache:rebuild
drush config:import || true
drush config:import
drush deploy:hook
drush cache:rebuild

.env support

Drainpipe will add .env file support for managing environment variables.

This is only used for locals - other environments such as CI and production should use their native environment variable mechanisms.

This consists of:

• Creation of a .env and .env.defaults file
• Default Taskfile.yml contains dotenv support note: real environment variables will override these
• Drupal integration via vlucas/phpdotenv To enable this, add the following to your composer.json:

  "autoload-dev":
  {
    "files": [
      "vendor/lullabot/drainpipe/scaffold/env/dotenv.php"
    ]
  },
  

  You will need to restart DDEV if you make any changes to .env or.env.defaults

SASS Compilation

This compiles CSS assets using Sass. It also supports the following:

• Globbing

  // Base
  @use "sass/base/**/*";
  

• Modern Normalizer
• Autoprefixer configured through a .browserslistrc file in the project root

Setup

• Add @lullabot/drainpipe-sass to your project yarn add @lullabot/drainpipe-sass or npm install @lullabot/drainpipe-sass
• Edit Taskfile.yml and add DRAINPIPE_SASS in the vars section

  vars:
    DRAINPIPE_SASS: |
      web/themes/custom/mytheme/style.scss:web/themes/custom/mytheme/style.css
      web/themes/custom/myothertheme/style.scss:web/themes/custom/myothertheme/style.css
  

• Run task sass:compile to check it works as expected
• Run task sass:watch to check file watching works as expected
• Add the task to a task that compiles all your assets e.g.

  assets:
    desc: Builds assets such as CSS & JS
    cmds:
      - yarn install --immutable --immutable-cache --check-cache
      - task: sass:compile
      - task: javascript:compile
  assets:watch:
    desc: Builds assets such as CSS & JS, and watches them for changes
    deps: [sass:watch, javascript:watch]
  

JavaScript Compilation

JavaScript bundling support is via esbuild.

Setup

• Add @lullabot/drainpipe-javascript to your project yarn add @lullabot/drainpipe-javascript or npm install @lullabot/drainpipe-javascript
• Edit Taskfile.yml and add DRAINPIPE_JAVASCRIPT in the vars section

  DRAINPIPE_JAVASCRIPT: |
    web/themes/custom/mytheme/script.js:web/themes/custom/mytheme/script.min.js
    web/themes/custom/myotherthemee/script.js:web/themes/custom/myothertheme/script.min.js
  

  Source and target need to have the same basedir (web or docroot) due to being unable to provide separate entryNames. See https://github.com/evanw/esbuild/issues/224
• Run task javascript:compile to check it works as expected
• Run task javascript:watch to check file watching works as expected
• Add the task to a task that compiles all your assets e.g.

  assets:
    desc: Builds assets such as CSS & JS
    cmds:
      - yarn install --immutable --immutable-cache --check-cache
      - task: sass:compile
      - task: javascript:compile
  assets:watch:
    desc: Builds assets such as CSS & JS, and watches them for changes
    deps: [sass:watch, javascript:watch]
  

Testing

This is provided by the separate drainpipe-dev package (so the development/testing dependencies aren't installed in production builds).

Static Tests

All the below static code analysis tests can be run with task test:static

| Test Type | Task Command | Description | |-----------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Security | task test:security | Runs security checks for composer packages against the FriendsOfPHP Security Advisory Database and Drupal core and contributed modules against Drupal's Security Advisories. | | Lint | task test:lint | - YAML lint on .yml files in the web directory<br />- Twig lint on files in web/modules, web/profiles, and web/themes<br />- composer validate<br />These cannot currently be customised. See #9.