Development

Typical development workflow

1. Pull the latest changes from the remote repository.
2. Fetch the latest database dump from the production environment with ahoy fetch-db.
3. Build the project with ahoy build.
4. Start a new feature or bugfix branch:
   • Create a new branch from develop.
   • Implement the feature or fix the bug.
5. Run tests:
   • Run automated tests locally.
   • Fix any failing tests.
6. Run code quality checks:
   • Run static code analysis locally.
   • Fix any issues reported.
7. Commit changes to the branch and push it to the remote repository.
8. Create a pull request:
   • Create a pull request from the branch to develop.
   • Assign reviewers.
   • Wait for the continuous integration pipeline to pass.

Switching branches

When switching to a new branch, there is no need to run ahoy build again as it may take a long time to rebuild the entire project. Instead, you can run these commands as needed based on what changed:

# Update Composer dependencies (if composer.json/composer.lock changed)
ahoy composer install

# Rebuild frontend assets (if theme files changed)
ahoy fe

# Provision site (if database or configuration changes expected)
ahoy provision

Fetching database

To fetch the database with the latest data from the production environment, use the ahoy fetch-db command, which will download the latest database dump from the production environment into a .data directory.

note

The database dump is stored in the .data directory instead of being directly imported into the local environment to allow for caching and reusing the database dump without needing to download it every time you need to refresh the local environment.

You can also manually download the database dump from the production environment and place it in the .data directory.

Refreshing database

Use ahoy provision to import the database dump into the local environment and run all the necessary updates. Run this command any time you need to reset the local environment to the database dump stored in .data.

Alternatively, you could use the ahoy import-db command (instead of ahoy provision) to import the database dump without running any updates. This is useful if you want to quickly reset the database without applying any updates or changes.

You can also export timestamped database dumps from the local environment into .data directory using the ahoy export-db command. You can then use these dumps to restore the local environment to a specific state: rename the dump file to .data/db.sql and run ahoy import-db.

See Drupal > Provision for more details.

Environment Variable Updates

To update environment variables in your local development environment:

1. Edit variables in .env.local file
2. Apply changes by restarting containers:

   ahoy restart

For more comprehensive variable reference, see Variables.

Debugging with Xdebug

To enable Xdebug for debugging:

ahoy debug-on  # Enable Xdebug
ahoy up        # Disable Xdebug

For complete Xdebug setup and IDE configuration, see Tools > Xdebug.

Working with Composer packages

Installing

To install packages, use composer require to include the package and resolve dependencies.

composer require drupal/devel

By default, stable releases are installed. If you need a non-stable version (e.g., alpha, beta, RC), specify the version constraint explicitly:

composer require drupal/devel:^1.0.0@beta

Make sure that the minimum-stability setting in composer.json is set to the version constraint you need. For example, to allow alpha, beta, and RC versions:

{
    "minimum-stability": "beta"
}

Adding JavaScript/CSS Libraries (npm packages)

To install JavaScript or CSS libraries as Drupal libraries with Composer, they must be defined as inline Composer packages.

1. Define the package in composer.json under the repositories section:

{
    "repositories": [
         {
            "type": "package",
            "package": {
                "name": "gdsmith/jquery.easing",
                "type": "drupal-library",
                "version": "1.4.1",
                "source": {
                    "type": "git",
                    "url": "https://github.com/gdsmith/jquery.easing",
                    "reference": "1.4.1"
                }
            }
        }
    ]
}

2. Require the package using Composer:

composer require gdsmith/jquery.easing

Updating

To update all dependencies:

composer update

Updates and patches

If your project uses patches to modify dependencies, the update may fail if the patches are not compatible with the new versions of the dependencies.

A common solution is to remove the patches temporarily, run the update, and then reapply the patches one by one.

To update a specific package and its dependencies:

composer update vendor/package-name --with-dependencies

For updating Drupal core, use:

composer update "drupal/core-*" --with-dependencies

After updating core, review changes with git diff, especially modified scaffolding files like .htaccess, and commit them in a single commit.

Overriding paths

To override package installation paths, modify composer.json:

{
    "extra": {
        "installer-paths": {
            "web/libraries/chosen": [
                "npm-asset/chosen-js"
            ],
            "web/libraries/{$name}": [
                "type:drupal-library",
                "type:npm-asset",
                "type:bower-asset"
            ]
        }
    }
}

Patching

If you need to apply patches to included dependencies, use the composer-patches plugin. Add the patch definition in composer.json under the extra.patches section:

"extra": {
    "patches": {
        "drupal/foobar": {
            "Patch description": "URL or local path to patch"
        }
    }
}

Run composer update drupal/foobar after adding patches to apply them.

Resetting the codebase

To reset the local environment, use the ahoy reset command. This command will stop and remove all containers and downloaded dependency packages (vendor, node_modules etc.).

To fully reset the repository to a state as if it was just cloned, use the ahoy reset hard command.