Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
3bd47ef
[#3325] Added a Drush listener that blocks 'sql:sync', 'sql:drop', 's…
AlexSkrypnyk Nov 16, 2026
8917e6c
[#3325] Documented the Drush production guard and the 'VORTEX_DRUSH_P…
AlexSkrypnyk Nov 16, 2026
3aa9f77
Updated snapshots.
AlexSkrypnyk Nov 16, 2026
b7e6b32
[#3325] Stopped event propagation for a blocked command so 'core:rsyn…
AlexSkrypnyk Nov 16, 2026
3e3de46
Updated snapshots.
AlexSkrypnyk Nov 16, 2026
a431377
[#3325] Removed the unneeded 'LowerCamelName' PHPCS suppression from …
AlexSkrypnyk Nov 16, 2026
61341e7
Updated snapshots.
AlexSkrypnyk Nov 16, 2026
b0f995c
[#3325] Fixed the production aliases config read passing an array def…
AlexSkrypnyk Nov 16, 2026
6952546
Updated baseline.
AlexSkrypnyk Nov 16, 2026
76e417d
[#3325] Replaced the production alias 'foreach' loop with 'array_any()'.
AlexSkrypnyk Nov 16, 2026
6d98e3b
Updated baseline.
AlexSkrypnyk Nov 16, 2026
dbac1b8
[#3325] Removed the 'preprod' alias example that the docs spellcheck …
AlexSkrypnyk Nov 16, 2026
6e0dbe0
Re-triggered CI to clear a flaky check.
AlexSkrypnyk Nov 16, 2026
7138daa
Addressed code review: matched production aliases against the request…
AlexSkrypnyk Nov 17, 2026
28975c3
Updated snapshots.
AlexSkrypnyk Nov 17, 2026
70c1a6e
[#3325] Replaced the 'match' alias stub with a lookup map and declare…
AlexSkrypnyk Nov 17, 2026
c17f837
Updated snapshots.
AlexSkrypnyk Nov 17, 2026
a7af985
[#3325] Stubbed the concrete 'SiteAliasManager' in 'ProductionGuardLi…
AlexSkrypnyk Nov 17, 2026
4c528a5
Updated snapshots.
AlexSkrypnyk Nov 17, 2026
f92b8a2
[#3325] Moved the production guard logic into 'drevops/vortex-tooling…
AlexSkrypnyk Nov 17, 2026
4c3caab
[#3325] Documented overriding the production guard stub and the tooli…
AlexSkrypnyk Nov 17, 2026
4ba0bcd
Updated baseline.
AlexSkrypnyk Nov 17, 2026
6cbd045
Removed the orphaned installer fixture deltas for the moved 'Producti…
AlexSkrypnyk Nov 17, 2026
58f2b3a
[#3325] Skipped declaring the production guard stub when the installe…
AlexSkrypnyk Nov 17, 2026
622dd73
Updated baseline.
AlexSkrypnyk Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .github/workflows/vortex-test-common.yml
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,18 @@ jobs:
./tests/lint.ci.sh
working-directory: .vortex

- name: Install tooling PHP dependencies
run: composer --working-dir=tooling install
working-directory: .vortex

- name: Lint tooling PHP code
run: composer --working-dir=tooling lint
working-directory: .vortex

- name: Test tooling PHP code
run: composer --working-dir=tooling test
working-directory: .vortex

# Special case to validate Renovate configuration with the same action
# as used in the Renovate workflow to ensure that they both use the same
# version.
Expand Down
20 changes: 20 additions & 0 deletions .vortex/.ahoy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ commands:
yarn --cwd=tests install --frozen-lockfile
[ -d ./tooling/node_modules ] && rm -rf ./tooling/node_modules
yarn --cwd=tooling install --frozen-lockfile
[ -d ./tooling/vendor ] && rm -rf ./tooling/vendor
composer --working-dir tooling install
[ -d ./installer/vendor ] && rm -rf ./installer/vendor
composer --working-dir installer install
[ -d ./docs/node_modules ] && rm -rf ./docs/node_modules
Expand Down Expand Up @@ -123,6 +125,24 @@ commands:
[ ! -d tooling/node_modules ] && yarn --cwd=tooling install --frozen-lockfile
tooling/node_modules/.bin/bats --no-tempdir-cleanup --tap "$@"

lint-tooling:
usage: Lint tooling PHP code.
cmd: |
[ ! -d tooling/vendor ] && composer --working-dir tooling install
composer --working-dir tooling lint

lint-tooling-fix:
usage: Fix tooling PHP code.
cmd: |
[ ! -d tooling/vendor ] && composer --working-dir tooling install
composer --working-dir tooling lint-fix

test-tooling:
usage: Run tooling PHPUnit tests.
cmd: |
[ ! -d tooling/vendor ] && composer --working-dir tooling install
composer --working-dir tooling test "$@"

test-common:
cmd: ./tests/test.common.sh

Expand Down
13 changes: 12 additions & 1 deletion .vortex/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ vortex/
| `docs/` | Docusaurus, Jest | vortextemplate.com |
| `installer/` | Symfony Console, PHPUnit | Template customization |
| `tests/` | PHPUnit | Template integration testing |
| `tooling/` | Bash, BATS | 'drevops/vortex-tooling' pkg |
| `tooling/` | Bash, BATS, PHP, PHPUnit | 'drevops/vortex-tooling' pkg |

Each subsystem has its own CLAUDE.md - read it when working there:

Expand Down Expand Up @@ -58,6 +58,15 @@ projects install it and run the shipped scripts from `vendor/bin/vortex-*`.
- **Manual** - `tooling/playground/` holds scripts that hit live services
(Slack, JIRA, New Relic). Not automated; see
`tooling/playground/README.md`.
- **PHP unit** - PHPUnit tests in `tooling/tests/Drush/` cover the PHP
classes in `tooling/src/Drush/`. Run with `ahoy test-tooling`, lint with
`ahoy lint-tooling` from `.vortex/`.

**Drush listeners**: Drush discovers listeners only in a project's
`drush/Listeners/` directory, never in `vendor/`. A listener's logic lives
in `tooling/src/Drush/` (all methods `protected`, no static `create()`),
and the template's `drush/Listeners/` holds a class that extends it and
declares `#[AsEventListener]`, which PHP does not inherit.

**Script pattern**: the structure, the variable block and the five output
helpers live in the boilerplate at
Expand Down Expand Up @@ -115,6 +124,8 @@ ahoy install # Install all dependencies
ahoy update-snapshots # Update fixtures (see Snapshots below)
ahoy lint-scripts # Lint scripts
ahoy test-bats # Run BATS unit tests
ahoy test-tooling # Run tooling PHPUnit tests
ahoy lint-tooling # Lint tooling PHP code
ahoy update-docs # Regenerate docs variables from scripts
ahoy lint-markdown # Lint markdown files
```
Expand Down
53 changes: 48 additions & 5 deletions .vortex/docs/content/contributing/maintenance/tooling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ sidebar_position: 4

`.vortex/tooling/` holds the shell scripts that consumer projects run for
provisioning, database work, deployment, notifications and helpers such as
`doctor` and `info`. This page is for contributors who change the scripts:
`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
Expand All @@ -27,16 +28,20 @@ The following table lists the contents of `.vortex/tooling/`:
| Path | Purpose |
|------|---------|
| `src/` | The shipped scripts; the only directory in the published archive |
| `composer.json` | The package definition, with the user-facing scripts under `bin` and no `version` field |
| `src/Drush/` | PHP classes in the `DrevOps\VortexTooling\Drush` namespace, which Composer loads through PSR-4 |
| `composer.json` | The 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.xml` | The PHP lint and test configuration, scoped to `src/Drush/` and `tests/Drush/` |
| `package.json`, `yarn.lock` | The `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`, `LICENSE` | The package readme and license, which ship with the scripts |
| `.gitattributes`, `.gitignore` | The Git settings, which stay out of the published archive |

`.gitattributes` marks only `.gitattributes`, `.gitignore`, `playground/`
and `tests/` as `export-ignore`. The published archive holds the rest:
`.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`
Expand Down Expand Up @@ -110,9 +115,28 @@ 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 scripts at 3 levels:
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
Expand Down Expand Up @@ -149,6 +173,25 @@ Tests cover the scripts at 3 levels:
`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/`:

```shell
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](template.mdx#test-the-template).
Expand Down
122 changes: 121 additions & 1 deletion .vortex/docs/content/development/environment/drush.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,11 @@ The shipped Drush configuration lives in the `drush/` directory:
passes `--disable-ssl` to the `sql:*` commands (`sql:cli`, `sql:query`,
`sql:dump`, `sql:drop`, `sql:create`) and to `site:install`. The database
commands then connect to the stack's database service without TLS. The
file also adds `--no-tablespaces` to `sql:dump`.
file also adds `--no-tablespaces` to `sql:dump` and lists the production
site aliases. See [Production guard](#production-guard).
- [`drush/Listeners/ProductionGuardListener.php`](https://github.com/drevops/vortex/blob/main/drush/Listeners/ProductionGuardListener.php)
registers the production guard, whose logic ships in
`drevops/vortex-tooling`. See [Production guard](#production-guard).
- [`drush/sites/lagoon.site.yml`](https://github.com/drevops/vortex/blob/main/drush/sites/lagoon.site.yml)
defines the site aliases for Lagoon-hosted environments. See
[Aliases](#aliases).
Expand Down Expand Up @@ -250,3 +254,119 @@ machine:
```
</TabItem>
</Tabs>

## Production guard

**Vortex** blocks 4 destructive Drush commands when they target a
production site alias. A mistyped `drush sql:sync @self @prod` then fails
before it overwrites the production database. The following table lists
the guarded commands and the alias the guard checks for each one:

| Command | Alias the guard checks |
|----------------|----------------------------------------------------------|
| `sql:sync` | The target, such as `@prod` in `drush sql:sync @self @prod` |
| `core:rsync` | The target, such as `@prod` in `drush core:rsync @self:%files @prod:%files` |
| `sql:drop` | The selected site, such as `@prod` in `drush @prod sql:drop` |
| `site:install` | The selected site, such as `@prod` in `drush @prod site:install` |

A blocked command stops before Drush connects to the site, and Drush prints
this error:

```text
[error] Refusing to run sql:drop against the production site alias @prod. Set VORTEX_DRUSH_PRODUCTION_GUARD_SKIP=1 to bypass this guard.
```

The guard checks the alias where you type the command. A command you run on
the production server itself, such as after `drush @prod ssh`, targets no
alias, so the guard lets it run.

### Production aliases

`drush/drush.yml` lists the production aliases under
`vortex.production_aliases`:

```yaml
vortex:
production_aliases:
- prod
```

An entry matches the alias with that name and every alias whose environment
has that name. The `prod` entry matches `@prod`, `@self.prod` and
`@lagoon.prod`. It doesn't match `@production`. An entry with a site name,
such as `lagoon.main`, matches only that alias.

On Lagoon, the alias of the production environment is
`@lagoon.<branch>`, where `<branch>` is the value of
`VORTEX_LAGOON_PRODUCTION_BRANCH`. With the default `main` branch, add
`lagoon.main` to the list:

```yaml
vortex:
production_aliases:
- prod
- lagoon.main
```

### Bypass the guard

To run a guarded command against production on purpose, set
`VORTEX_DRUSH_PRODUCTION_GUARD_SKIP` to `1` for that command. Drush prints a
warning that names the variable, then runs the command:

<Tabs>
<TabItem value="host" label="Host" default>
```shell
VORTEX_DRUSH_PRODUCTION_GUARD_SKIP=1 drush @prod sql:drop
```
</TabItem>
<TabItem value="ahoy" label="Ahoy">
```shell
VORTEX_DRUSH_PRODUCTION_GUARD_SKIP=1 ahoy drush @prod sql:drop
```
</TabItem>
<TabItem value="docker-compose" label="Docker Compose">
```shell
docker compose exec -e VORTEX_DRUSH_PRODUCTION_GUARD_SKIP=1 cli \
drush @prod sql:drop
```
</TabItem>
</Tabs>

Set the variable on the command line only. An `export` in your shell turns
off the guard for every command that follows.

### Change the guard

The guard's logic lives in the
`DrevOps\VortexTooling\Drush\ProductionGuardListener` class of
`drevops/vortex-tooling`, so tooling updates bring fixes to your project.
Drush finds the guard through `drush/Listeners/ProductionGuardListener.php`,
which extends that class and adds nothing else. With a tooling version that
doesn't ship the class, the file declares nothing and the guard stays off
until you update `drevops/vortex-tooling`.

To change a rule for your project, override the matching method in
`drush/Listeners/ProductionGuardListener.php`. For example, to also guard
`sql:create` against the selected site:

```php
use Symfony\Component\Console\Input\InputInterface;

#[AsEventListener(priority: 100)]
class ProductionGuardListener extends VortexProductionGuardListener {

protected function resolveTargetAliases(string $command, InputInterface $input): array {
if ($command === 'sql:create') {
return [$this->siteAliasManager()->getSelf()->name()];
}

return parent::resolveTargetAliases($command, $input);
}

}
```

Keep the `#[AsEventListener(priority: 100)]` line. Drush registers the guard
only when the class in `drush/Listeners/` declares it, and the priority runs
the guard before `core:rsync` connects to the target.
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?php

declare(strict_types=1);

namespace Drush\Listeners;

use DrevOps\VortexTooling\Drush\ProductionGuardListener as VortexProductionGuardListener;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

// Releases of 'drevops/vortex-tooling' before the guard do not ship the
// parent class; declaring the subclass then would break every Drush command.
if (!class_exists(VortexProductionGuardListener::class)) {
return;
}

/**
* Refuses destructive Drush commands that target a production site alias.
*
* Override a method of the parent class to change the guard for this project.
*
* The priority runs the guard before the 'core:rsync' command event hook,
* which connects to the target to evaluate its path.
*/
#[AsEventListener(priority: 100)]
class ProductionGuardListener extends VortexProductionGuardListener {

}
Original file line number Diff line number Diff line change
@@ -1,3 +1,12 @@
vortex:
# Site aliases that 'sql:sync', 'sql:drop', 'site:install' and 'core:rsync'
# refuse to target. An entry matches the alias with that name and any alias
# whose environment has that name: 'prod' matches '@prod' and '@site.prod'.
# Set VORTEX_DRUSH_PRODUCTION_GUARD_SKIP=1 to bypass the guard.
# @see drush/Listeners/ProductionGuardListener.php
production_aliases:
- prod

command:
sql:
cli:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
<file>web/themes/custom</file>
<file>web/sites/default/settings.php</file>
<file>web/sites/default/includes</file>
<file>drush/Listeners</file>
<file>tests</file>
<file>scripts</file>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ parameters:
- web/themes/custom
- web/sites/default/settings.php
- web/sites/default/includes
- drush/Listeners
- tests
- scripts

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,7 @@
<directory>web/themes/custom</directory>
<directory>web/sites/default/includes</directory>
<directory>web/sites/default/settings.php</directory>
<directory>drush/Listeners</directory>
</include>
<exclude>
<directory suffix="Test.php">web/modules/custom</directory>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
__DIR__ . '/web/themes/custom',
__DIR__ . '/web/sites/default/settings.php',
__DIR__ . '/web/sites/default/includes',
__DIR__ . '/drush/Listeners',
__DIR__ . '/tests',
])
->withSkip([
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
@@ -12,18 +12,18 @@
@@ -12,19 +12,19 @@
<!-- Lint code against platform version specified in composer.json key "config.platform.php". -->
<config name="testVersion" value="8.4"/>

Expand All @@ -10,6 +10,7 @@
+ <file>docroot/themes/custom</file>
+ <file>docroot/sites/default/settings.php</file>
+ <file>docroot/sites/default/includes</file>
<file>drush/Listeners</file>
<file>tests</file>
<file>scripts</file>

Expand Down
Loading
Loading