Composer Plugin to prepare Drupal project for CI and/or local tests.

Installs: 5 533

Dependents: 0

Suggesters: 0

Security: 0


2.10.3 2022-09-03 16:36 UTC


This project needs a new name and a new home (ideally managed by the Drupal Association). This plugin has 2 goals:

  • CI template. Provide a golden path (see Spotify's definition of this term) that Drupal contrib projects can use with Gitlab CI.
  • Local development. Standardize scripts and a matching codebase assembly for local Drupal development.

Together, these goals ensure that tests run on local environment have same outcome as on the Gitlab CI platform (to a large extent).


  • Add a .gitlab-ci.yml in the project root dir. An example is KeyCDN. Commit and push the file.
  • Pipelines should start running after each push. Click Gitlab's CI/CD link to see them.
  • Add a phpcs.xml file to customize how phpcs checks your source code.
  • You may add services to your .gitlab-ci.yml file if you want to test with memcache, elasticsearch, redis, etc.
  • Optional. Add patches as per usual in composer.json if you need changes in other packages (for example).
  • Optional (maintainers only). Go to CI/CD => Schedules and add any important build permutations to a weekly schedule. Example permutations would be a non-default Drupal core version, DB backend, etc. For example, see KeyCDN's schedules. See Environment Variables below.

Environment Variables

Use the Run Pipeline button on your Pipelines listing to test any branch with alternate versions of Drupal core, PHP version, or DB driver. The recognized variables and default values are:

  • DB_DRIVER recognizes mysql, sqlite, or pgsql.

Local Development

  • Clone the contrib project via git
  • Install this plugin (syntax depends on your shell):
    • BASH or ZSH: bash <(curl -s https://gitlab.com/drupalspoons/composer-plugin/-/raw/master/bin/setup)
    • FISH: bash (curl -s https://gitlab.com/drupalspoons/composer-plugin/-/raw/master/bin/setup | psub)
  • Configure a web server to serve the /web directory as docroot. Either of these works fine:
    • composer webserver
    • Setup Apache/Nginx/Other. A virtual host works fine. Any domain name works.
  • Configure a database server and create a database.
  • Install Drupal composer si -- --db-url=mysql://user:pass@localhost/db. Adjust as needed.
  • Run tests composer unit.
  • Customize these composer scripts via environment variables and args/options. See the table above.

This plugin is compatible with any Docker local development platform like DDEV, Lando, etc. Further, this plugin doesn't assume Docker so native is great too. A convenient way to set environment variables on native is Direnv (and see the .envrc file thats written into your project root). Alternatively, prefix all Composer commands with spoon like spoon update or spoon drush core:status

Handling project changes

  • If the project's composer.json changes or if files are added/removed from project root: composer drupalspoons:rebuild
  • If new or updated dependencies are available composer update

More example commands

  • Run all tests - composer unit.
  • Run a suite: composer unit -- --testsuite functional
  • Skip slow tests: composer unit -- --exclude-group slow
  • Use a different URL: SIMPLETEST_BASE_URL=http://example.com composer unit

How this plugin works

  • This plugin writes a composer.spoons.json file that includes the specified version of Drupal core.
  • The plugin assumes that composer.spoons.json is in effect when running composer commands. This is done automatically for CI. For local development, COMPOSER=composer.spoons.json environment variable must be set. You can do that manually or via Direnv, or Docker, or spoon.
  • This plugin assembles a codebase using symlinks similar to:

Folder tree