Skip to main content
Version: v1

Tooling

.vortex/tooling/ holds the shell scripts that consumer projects run for provisioning, database work, deployment, notifications and helpers such as doctor and info, and the PHP classes behind the project's Drush listeners. This page is for contributors who change the scripts: it covers the package layout, the script conventions, the test levels and how the package gets published. To use the scripts in a project, see Architecture > Automation scripts.

The scripts are published as the standalone drevops/vortex-tooling Composer package. Consumer projects install the package and run the user-facing scripts, the ones listed under bin in the package composer.json, from vendor/bin/vortex-*. The other scripts, such as the per-channel vortex-notify-* scripts, run through those entry points.

Package layout​

The following table lists the contents of .vortex/tooling/:

PathPurpose
src/The shipped scripts; the only directory in the published archive
src/Drush/PHP classes in the DrevOps\VortexTooling\Drush namespace, which Composer loads through PSR-4
composer.jsonThe package definition, with the user-facing scripts under bin, the PSR-4 autoload, the PHP development dependencies and no version field
tests/unit/BATS unit tests covering the shipped scripts and a few template scripts outside the package
tests/_helper.bash, tests/fixtures/The shared BATS setup and the fixture files the tests read
tests/Drush/PHPUnit tests covering the classes in src/Drush/
phpcs.xml, phpstan.neon, rector.php, phpunit.xmlThe PHP lint and test configuration, scoped to src/Drush/ and tests/Drush/
package.json, yarn.lockThe bats-helpers library that the BATS tests load; ahoy test-bats installs it on first run
playground/Manual scripts that hit live services (email, GitHub, Jira, New Relic, Slack, webhooks and S3); not automated
README.md, LICENSEThe package readme and license, which ship with the scripts
.gitattributes, .gitignoreThe Git settings, which stay out of the published archive

.gitattributes marks .gitattributes, .gitignore, playground/, tests/ and the PHP lint and test configuration files as export-ignore. The published archive holds the rest:

  • src/
  • composer.json
  • package.json and yarn.lock
  • README.md and LICENSE

While you develop Vortex itself, Composer installs the package from the in-tree copy, which the template's root composer.json declares as a path repository with a pinned version. The installer strips that entry, so Composer on consumer sites installs the published package from Packagist. The same version is also pinned in scripts/vortex-tooling.sh and .vortex/tests/phpunit/Traits/SutTrait.php. Release > Release process lists every spot to bump.

Script conventions​

Every shipped script follows the same pattern:

  1. An environment-loading header, which reads .env and .env.local and lets real environment variables win
  2. set -eu, with an opt-in VORTEX_DEBUG=1 trace
  3. Variables with defaults
  4. The shared output helpers

The output helpers have a strict contract:

  • info marks the start and the end of an operation.
  • task announces work that's starting. Every task must be closed by a pass or a fail, even when the work itself can't fail, so the output always shows whether a step succeeded.
  • pass reports success. It closes the open task, or it stands on its own for a check that holds or a step that's skipped or finished. In the shipped scripts, task also starts a timer, and pass appends the seconds the task took to its message.
  • note is a standalone remark that starts no task.
  • fail reports the failure and exits.

The following example closes a task whose command can't fail:

task "Disabling Search API Solr server."
drush search-api:server-disable solr || true
pass "Disabled Search API Solr server."

The || true in the example from scripts/provision-20-migration.sh is deliberate: the disable is best-effort, so a failed disable doesn't stop the script. The contract still requires the closing pass, so the step reports an outcome.

In a shipped script, a pass that closes a task prints [ OK ], the message and the task's duration in seconds, such as [ OK ] Disabled Search API Solr server. (2s). The provision subscripts in scripts/ define simpler helpers, so in the example's own script, pass prints the message after a + marker, with no duration.

See Template > Write scripts for the full authoring requirements shared by all shell scripts in the template.

Add a script​

To add a user-facing script:

  1. Create it in src/ as vortex-<name>, following the script conventions.
  2. Add src/vortex-<name> to the bin list in .vortex/tooling/composer.json.

Composer creates a vendor/bin entry only for the scripts in that list. Leave helper scripts off it: vortex-notify, for example, runs each vortex-notify-* channel script by path from src/.

Add a Drush listener​

Drush discovers listeners only in a project's drush/Listeners/ directory, so a listener class in vendor/ never runs on its own. Each listener therefore has 2 parts:

  1. The logic, as a class in src/Drush/ with its PHPUnit tests in tests/Drush/. Make every method protected, so a project can override any of them.
  2. A class in the template's drush/Listeners/ directory that extends the tooling class and declares #[AsEventListener]. PHP doesn't inherit attributes, so Drush reads the attribute from this class.

A listener must not have a static create() method. Drush registers such a listener only after a full Drupal bootstrap, which doesn't happen for a command against a remote alias. Set services through the Drush *AwareInterface inflection instead, as src/Drush/ProductionGuardListener.php does.

Test the tooling​

Tests cover the tooling at 4 levels:

  • Unit - BATS tests in tooling/tests/unit/ cover the shipped scripts with external commands mocked. The same suite also covers a few template scripts outside the package; see Template > Unit testing. Most test files are named after the script they cover, without its vortex- prefix, such as deploy.bats for vortex-deploy. Run the tests from .vortex/:

    cd .vortex

    # Run all BATS tests.
    ahoy test-bats tooling/tests/unit

    # Run a single test file.
    ahoy test-bats tooling/tests/unit/deploy.bats

    ahoy test-bats needs a path: without a path, BATS stops with Must specify at least one <test>. Each test runs the scripts from a copy of the repository at its last commit, so commit your changes before you run it. The exception is update-vortex.bats, which runs vortex-update from your working tree. The setup also expects curl, composer, docker, ahoy and jq on your PATH.

    ahoy test-bats runs BATS with --tap, so each test prints ok <n> <name> when it passes or not ok <n> <name> when it fails. The command exits with a non-zero code when any test fails.

    The Vortex - Test workflow (.github/workflows/vortex-test-common.yml) runs the whole suite in its vortex-test-common job. The job uses .vortex/tests/test.common.sh, the script behind ahoy test-common, which runs BATS on .vortex/tooling/tests/unit. The job also sets VORTEX_DEV_TEST_COVERAGE_DIR, so the script runs BATS through kcov and writes the scripts' code coverage to that directory.

  • PHP unit - PHPUnit tests in tooling/tests/Drush/ cover the classes in src/Drush/. Lint and test them from .vortex/:

    cd .vortex

    # Run the PHPUnit tests.
    ahoy test-tooling

    # Run PHP_CodeSniffer, PHPStan and Rector.
    ahoy lint-tooling

    # Fix the issues that Rector and PHP_CodeSniffer can fix.
    ahoy lint-tooling-fix

    Each command installs the tooling's Composer dependencies on first run. The vortex-test-common job runs the same lint and tests.

  • Integration - the template's PHPUnit functional tests in .vortex/tests/ run the scripts end-to-end. See Template > Test the template.

  • Manual - tooling/playground/ holds scripts that hit live services. They aren't automated; see tooling/playground/README.md.

Publish the package​

The Vortex - Publish tooling workflow (.github/workflows/vortex-publish-tooling.yml) mirrors .vortex/tooling/ to the drevops/vortex-tooling repository. It runs on every push to main, 2.x and any branch whose name contains vortex-tooling. The mirror branch takes the source branch name.

Each push publishes 1 commit to the mirror, which is empty when nothing in .vortex/tooling/ changed. Its subject matches the subject of the pushed commit. Its body records provenance in 2 lines, Source: drevops/vortex@<sha> and Branch: <branch>.

A branch that's new to the mirror starts there as an orphan with no shared history. Treat the mirror as read-only, because each publish replaces its files with the contents of .vortex/tooling/.

To confirm a publish, open the Vortex - Publish tooling run for your push. Its publish step ends with Published 'drevops/vortex@<sha>' to drevops/vortex-tooling#<branch>.

The workflow sets no package version, because Packagist reads it from the mirror's tags and branch names. Never hardcode a version in the package composer.json.

You tag tooling releases on the mirror repository. When the tooling has changed since the last release, tag it before the Vortex release, so the template can require the new tag. See Release > Tag a release.