Development
This section covers the day-to-day work on a Vortex project: running the local environment, managing the database and dependencies, working with the Drupal application, and checking your code with linters and tests.
Each page owns one task or tool and carries everything about it - daily usage, configuration, and how it behaves in the continuous integration pipeline - so there is one place to look. Larger topics are subsections whose overview page ties their pages together. This page describes the overall process and points to the right page for each task.
Typical development process
- 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 changes to the branch and push it 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
The most common day-to-day commands. Each video is a live recording captured on a demo consumer project that uses Vortex.
Build the project
ahoy build rebuilds the whole stack from scratch: it recreates the
containers, installs the Composer and front-end dependencies, compiles the
theme assets, and provisions the site from the database dump.
Show project information
ahoy info shows the current project information: the site URL, container
status and ports.
Run linters
ahoy lint runs all the code quality checks: back-end (PHPCS, PHPStan,
Rector), front-end (Twig CS Fixer, ESLint, Stylelint) and test linting
(Gherkin Lint).
Run unit, kernel and functional tests
ahoy test runs all the PHPUnit test suites: unit, kernel, functional and
functional JavaScript.
Run BDD tests
ahoy test-bdd runs the Behat tests against the provisioned site, driving a
real browser inside the container stack.
Re-provision the site
ahoy provision re-imports the database dump from .data/db.sql into the
running stack and applies the provisioning steps: database updates,
configuration import, cache rebuilds and deploy hooks.
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 ──► Sanitize database ──► Store database cache │ │
│ │ trigger database Remove sensitive data │ │
│ │ │ │
│ └─────────────────────────────────────┬──────────────────────────────────────────────┘ │
│ │ Provides cached database │
│ ▼ │
│ ┌─ Lint Job ────────────┐ ┌─ Database Job ────────────────┐ ┌─ Audit Job ──────────┐ │
│ │ │ │ ◆ Nightly cache exists? │ │ Composer audit │ │
│ │ Build CLI container │ │ Yes ──► job succeeds │ │ (advisories) │ │
│ │ ▼ │ │ No ──► download, sanitize, │ │ ▼ │ │
│ │ Composer validate │ │ store cache │ │ Gitleaks │ │
│ │ ▼ │ └───────────────┬───────────────┘ │ (committed secrets) │ │
│ │ Composer normalize │ ▼ │ │ │
│ │ ▼ │ ┌─ Build Job ───────────────────┐ │ │ │
│ │ Hadolint │ │ Code assembly │ │ │ │
│ │ ▼ │ │ Docker, Composer deps, │ │ │ │
│ │ DCLint │ │ NPM deps, assets │ │ │ │
│ │ ▼ │ │ ▼ │ │ │ │
│ │ PHPCS │ │ Website setup │ │ │ │
│ │ ▼ │ │ Import cached DB, drush │ │ │ │
│ │ PHPStan │ │ deploy, custom scripts │ │ │ │
│ │ ▼ │ │ ▼ │ │ │ │
│ │ Rector │ │ Testing │ │ │ │
│ │ ▼ │ │ PHPUnit tests ──► Behat tests │ │ │ │
│ │ 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
| Page | Description |
|---|---|
| Environment | The container stack, Ahoy, Drush, Doctor, Pygmy, debugging |
| Composer | Managing packages, patching, security auditing, the shipped composer.json |
| Provision | Fetching and importing databases, the provisioning flow, deploy hooks |
| Settings | Environment type detection and per-module settings overrides |
| Modules | Every shipped module, the module scaffold, Drupal helpers, generated content, 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, 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
Every tool Vortex ships, and where it is documented.
| Tool | Documented in |
|---|---|
| Ahoy | Environment > Ahoy |
| 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 |
| Stylelint | Code quality > Stylelint |
| Twig CS Fixer | Code quality > Twig CS Fixer |
| Xdebug | Environment > Debugging |