Development
This section is for developers who build features and fix bugs on a project created from Vortex. It covers the day-to-day work in 4 areas:
- Running the local environment
- Managing the database and the dependencies
- Working with the Drupal application
- Checking your code with linters and tests
Most pages cover 1 task or tool: its daily usage, its configuration and how it runs in the continuous integration pipeline. A bigger topic gets a subsection with an overview page of its own. Use this page to follow the overall process and find the page for each task.
To set up the pipeline, the deployments or the hosting, see Continuous integration, Deployment and Hosting.
Typical development process
A change usually goes through these steps:
- Pull the latest changes from the remote repository.
- Fetch the latest database dump from the production environment.
- Build the project.
- Start a new feature or bugfix branch:
- Create a new branch from
develop(see Releasing > GitFlow for the branch structure). - Implement the feature or fix the bug.
- Create a new branch from
- Run tests:
- Run automated tests locally.
- Fix any failing tests.
- Run code quality checks:
- Run static code analysis locally.
- Fix any issues reported.
- Commit your changes to the branch.
- Push the branch to the remote repository.
- Create a pull request:
- Create a pull request from the branch to
develop. - Assign reviewers.
- Wait for the continuous integration pipeline to pass.
- Create a pull request from the branch to
Common commands
Each video in this section is a live recording of a demo project built from Vortex.
Build the project
ahoy build rebuilds the project from scratch. After you confirm, it runs
these steps in order:
- Removes the containers, the installed dependencies and the database.
- Builds and starts fresh containers.
- Installs the Composer and front-end dependencies.
- Compiles the custom theme's assets, when the project has a custom theme.
- Provisions the site.
- Prints the project information with a one-time login link.
Show project information
ahoy info prints what you need to reach the running project:
- The project name and the Docker Compose project name
- The site URL and the path to the web root
- The database host, username, password and port
- The database port on your host
- The database image, when
VORTEX_DB_IMAGEis set - The Solr and Storybook addresses, when their ports are mapped on your host
- The Selenium VNC address, where you can watch the browser tests run
- The mail catcher address
- Whether Xdebug is on
To print a one-time login link too, pass any argument, such as
ahoy info login. Without an argument, the output ends with a reminder to
run ahoy login, which unblocks user 1 and prints a one-time login link.
Run linters
ahoy lint runs 3 groups of linters. Each group also has a command of its
own:
ahoy lint-be: the backend linters PHPCS, PHPStan and Rectorahoy lint-fe: the frontend linters Twig CS Fixer, ESLint and Stylelintahoy lint-tests: Gherkin Lint for the Behat feature files
ahoy lint-fix applies the automatic fixes of Rector, PHPCBF (the PHPCS
fixer), Twig CS Fixer, ESLint and Stylelint.
SDC Devel validates the custom theme's components against a provisioned
site, so it runs separately as ahoy lint-sdc. Continuous integration runs
DCLint and Hadolint from their Docker images, so neither has an Ahoy
command.
Run unit, kernel and functional tests
ahoy test runs every PHPUnit suite: unit, kernel, functional and
functional JavaScript. To run 1 suite, use its own command:
ahoy test-unitahoy test-kernelahoy test-functionalahoy test-functional-javascript
The Jest tests for JavaScript run separately, with ahoy test-js.
Run BDD tests
ahoy test-bdd runs the Behat tests against the provisioned site. Scenarios
tagged @javascript drive a real browser in the chrome container. All
other scenarios send HTTP requests from PHP.
Re-provision the site
After you confirm, ahoy provision runs provisioning again in the running
stack. The database it starts from depends on the project:
- With
VORTEX_PROVISION_OVERRIDE_DBset to1, the command replaces the current database with the dump from.data/db.sql. - With
VORTEX_PROVISION_OVERRIDE_DBset to0, the command imports the dump only when no site is installed yet. - With the database in a container image (
VORTEX_DB_IMAGE), the command starts a fresh database container from that image, whateverVORTEX_PROVISION_OVERRIDE_DBsays.
.env sets VORTEX_PROVISION_OVERRIDE_DB to 0. .env.local.example sets
it to 1 for local work, after you copy that file to .env.local.
The provisioning steps run next, from the database updates and the
configuration import to the deploy hooks and your custom
scripts/provision-*.sh scripts. The command finishes with a one-time login
link.
Beyond local development
Expand to see the complete code lifecycle
Local Development
═════════════════════════════════════════════════════════════════════════════════════════
Developer writes code ──► Build and test locally ──► Commit changes
│
▼
Git Repository
═════════════════════════════════════════════════════════════════════════════════════════
Push to remote branch ──► Open/Update Pull Request
│
▼
┌─ CI Pipeline ────────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌─ Database Job (Nightly) ───────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Scheduled ──► Download production ──► Import and export ──► Store database cache │ │
│ │ trigger database to validate the dump │ │
│ │ │ │
│ └─────────────────────────────────────┬──────────────────────────────────────────────┘ │
│ │ Provides cached database │
│ ▼ │
│ ┌─ Lint Job ────────────┐ ┌─ Database Job ────────────────┐ ┌─ Audit Job ──────────┐ │
│ │ │ │ ◆ Nightly cache exists? │ │ Composer audit │ │
│ │ Composer validate │ │ Yes ──► job succeeds │ │ (advisories) │ │
│ │ ▼ │ │ No ──► download, validate, │ │ ▼ │ │
│ │ Hadolint │ │ store cache │ │ npm audit │ │
│ │ ▼ │ └───────────────┬───────────────┘ │ (advisories) │ │
│ │ DCLint │ ▼ │ ▼ │ │
│ │ ▼ │ ┌─ Build Job ───────────────────┐ │ Gitleaks │ │
│ │ Build CLI container │ │ Code assembly │ │ (committed secrets) │ │
│ │ ▼ │ │ Docker, Composer deps, │ │ │ │
│ │ Composer normalize │ │ NPM deps, assets │ │ │ │
│ │ ▼ │ │ ▼ │ │ │ │
│ │ PHPCS │ │ Website setup │ │ │ │
│ │ ▼ │ │ Import cached DB, drush │ │ │ │
│ │ PHPStan │ │ deploy, custom scripts │ │ │ │
│ │ ▼ │ │ ▼ │ │ │ │
│ │ Rector │ │ Testing │ │ │ │
│ │ ▼ │ │ Jest ──► PHPUnit ──► Behat │ │ │ │
│ │ Twig CS Fixer │ └───────────────┬───────────────┘ │ │ │
│ │ ▼ │ │ │ │ │
│ │ Gherkin Lint │ │ │ │ │
│ │ ▼ │ │ │ │ │
│ │ ESLint / Stylelint │ │ │ │ │
│ │ │ │ │ │ │
│ └──────────┬────────────┘ │ │ │ │
│ │ │ │ │ │
│ ▼ ▼ │ │ │
│ ┌─ Deployment Job ─────────────────────────────────────────┐ │ │ │
│ │ │ │ │ │
│ │ Webhook Artifact Lagoon │ │ Does not gate │ │
│ │ Call URL Package artifact Run Lagoon CLI deploy │ │ deployment │ │
│ │ │ │ │ │
│ └──────────────────────────────────────────────────────────┘ └──────────────────────┘ │
│ │
└─────────────────────────────────── ───────────────────────────────────────────────────────┘
│
▼
Hosting Platform
═════════════════════════════════════════════════════════════════════════════════════════
◆ Environment ──No──► Sync DB from production ───┐
exists? │
│ Yes ▼
└──────────────────────────────────► drush deploy ──► Custom scripts ──► Notifications
Available Environments
═════════════════════════════════════════════════════════════════════════════════════════
┊ PR Environment ┊ Dev Staging Production
┊ (auto-removed) ┊ develop branch main branch production branch or tag
In this section
The following table lists the pages in this section:
| Page | Description |
|---|---|
| Environment | The container stack, Ahoy, Drush, Doctor, Pygmy, debugging, logs and troubleshooting |
| Composer | Managing packages, patching, security auditing and the shipped composer.json |
| Provision | Fetching and importing databases, the provisioning flow and deploy hooks |
| Settings | Environment type detection and per-module settings overrides |
| Modules | Every shipped module, the module scaffold, Drupal helpers, generated content and Testmode |
| Themes | The theme scaffold and its build system |
| Migrations | The optional second database powering Drupal migrations |
| Code quality | The linters and how to run them |
| Testing | PHPUnit, Behat and Jest |
| Security | Secret scanning, dependency auditing and environment access |
| Visual regression | Diffy-powered visual regression on deployments |
| Dependency updates | Automated dependency updates with Renovate |
| AI | The AI agent configuration files |
| FAQs | Answers to common operational questions |
| Variables | The full environment variable reference |
Tools
The following table lists the tools that Vortex ships and the page that documents each one:
| Tool | Documented in |
|---|---|
| Ahoy | Environment > Ahoy |
audit-ci | Security > Dependency audit |
| Behat | Testing > Behat |
| Composer | Composer |
| DCLint | Code quality > DCLint |
| Diffy | Visual regression > Diffy |
| Docker | Environment > Docker |
| Doctor | Environment > Doctor |
| Drush | Environment > Drush |
| ESLint | Code quality > ESLint |
| Gherkin Lint | Code quality > Gherkin Lint |
| Git artifact | Deployment > Artifact > Git artifact tool |
| Gitleaks | Security > Secret scanning |
| Hadolint | Code quality > Hadolint |
| Jest | Testing > Jest |
| PHPCS | Code quality > PHPCS |
| PHPStan | Code quality > PHPStan |
| PHPUnit | Testing > PHPUnit |
| Pygmy | Environment > Pygmy |
| Rector | Code quality > Rector |
| Renovate | Dependency updates |
| SDC Devel | Code quality > SDC Devel |
| Storybook | Themes > Storybook |
| Stylelint | Code quality > Stylelint |
| Twig CS Fixer | Code quality > Twig CS Fixer |
| Xdebug | Environment > Debugging |