Wunder template for DDEV Drupal projects

This project extends the standard DDEV setup with additional functionality and tools specifically designed for Drupal development. It provides a set of custom commands, configurations, and automation scripts to enhance your Drupal development workflow.

Installation

Requirements

• DDEV >= 1.24.3

Steps

1. Initialize your Drupal project. Project name parameter is optional, but it’s advisable to use domain name as your project name as that’s used for the subdomain of ddev.site eg if project name is example.com, then localhost URL will become example.com.ddev.site.

   ddev config --project-type=drupal11 --docroot=web --project-name=example.com
   

   Choose major version of Drupal based on your actual Drupal (e.g., 10 or 11).

2. Install Wunderio DDEV Drupal as a DDEV add-on and restart DDEV:

   ddev add-on get wunderio/ddev-wunderio-drupal && ddev restart
   

3. Optionally if you have GrumPHP installed:

   • Default setup (recommended): In many setups the default php used by GrumPHP works out of the box and you do not need any custom EXEC_GRUMPHP_COMMAND in grumphp.yml.
   • If you previously added a custom EXEC_GRUMPHP_COMMAND for DDEV/Lando: You can safely remove the entire git_hook_variables section from grumphp.yml and then re‑initialise the hooks so they use the default configuration.

   After adjusting grumphp.yml, re‑init the hook:

   ddev grumphp git:init
   

4. Add changes to GIT (note that below command uses -p, so you need to say ‘y’es or ‘n’o if it asks what to commit):

   git add .ddev/ &&
   git add drush/sites/ &&
   git add -p web/sites/default/settings.php grumphp.yml &&
   git commit
   

   Also note that whenever you update wunderio/ddev-wunderio-drupal add-on, you need to add everything under .ddev to GIT.

Updating the add-on

• To update the add-on to the latest version:

  ddev add-on get wunderio/ddev-wunderio-drupal
  

Features

For a quick reference in your project’s README, add:

This project uses [ddev-wunderio-drupal](https://github.com/wunderio/ddev-wunderio-drupal) DDEV add-on. Run `ddev -h` to see all available commands.

Custom DDEV Commands

• pmu: Runs drush pmu commands and creates dummy module folders if they don’t exist. This helps to uninstall module that has gone missing for example during branch switching.

  ddev pmu module1 module2 ...
  

• twig-debug: Toggles Drupal Twig debugging on/off. Useful for template development.

  ddev twig-debug        # Enable Twig debugging
  ddev twig-debug off    # Disable Twig debugging
  

• grumphp: Runs GrumPHP commands.

  ddev grumphp
  

• phpunit: Runs PHPUnit commands.

  ddev phpunit
  

• regenerate-phpunit-config: Regenerates fresh PHPUnit configuration. Run this if you don’t have phpunit configured in your project.

  ddev regenerate-phpunit-config
  

• codecept: Runs codeception commands.

  ddev codecept
  

• phpcbf: Runs PHPCBF commands.

  ddev phpcbf
  

• phpcs: Runs PHPCS commands.

  ddev phpcs
  

• phpstan: Runs PHPStan commands. Usually, the directory to be scanned is web/modules/custom or a specific module within that directory.

  ddev phpstan analyze <directory-or-module-to-be-scanned>
  

• syncdb: Synchronizes local database from a remote environment. Requires aliases in drush/sites/self.site.yml.

  ddev syncdb <alias>                   # e.g. ddev syncdb prod
  ddev syncdb prod --backup             # Back up local DB before overwriting
  ddev syncdb prod --keep-dump          # Keep the downloaded dump file
  ddev syncdb prod --no-deploy          # Skip running drush deploy after import
  ddev syncdb prod --backup --keep-dump # Combine flags
  

• yq: Runs yq commands (YAML processor). It’s available inside DDEV, but we expose it to host because why not :). It’s required in syncdb script, but it could prove useful in day to day work.

  ddev yq
  

• commit: Generates AI-powered commit messages from staged changes using the configured API. The command analyzes your staged changes and branch name to generate commit messages following the project’s commit message format (ticket/issue ID prefix, present tense, imperative mood). Requires OPENAI_API_URL and OPENAI_API_KEY environment variables to be configured via DDEV global config.

  ddev commit
  

  Setup: Configure the API credentials in DDEV global config (applies to all projects) and restart your DDEV project:

  ddev config global --web-environment-add="OPENAI_API_URL=https://your-api-url"
  ddev config global --web-environment-add="OPENAI_API_KEY=your-api-key"
  ddev restart
  

  Note: The global config is stored in ~/.ddev/global_config.yaml. You can edit this file directly if you prefer, then restart your DDEV project.

Enhanced Configuration

1. Custom DDEV Configuration
   • Post-start scripts for both host and web containers — by default it gives you a uli link.
   • Automatic update checks for this package.
2. Performance Optimizations
   • Special database_dumps/ directory for Mac users not to mount db dumps.

Automated Workflows

The project includes several automated workflows:

1. Database Management
   • Post-import and post-restore-snapshot hooks (sanitize database).
   • Database synchronization from remote environments via ddev syncdb.
   • Run ddev drush deploy after import to apply updates, import config, and rebuild caches.
2. Development Environment Setup
   • Automatic Composer installation on first start.
   • Post-start hook that runs drush uli.
   • Integration with Wunderio’s development tools, e.g. GrumPHP, PHPUnit.

Both custom commands and hooks are scripts under ~/.ddev/wunderio/core/ folder (note it’s your host home folder) and you can extend them if you copy particular script to your project .ddev/wunderio/custom/ folder. This folder is never overwritten during autoupdate.

Migration from Composer plugin (legacy)

Previously, this package was installed as a Composer plugin and deployed files into the project. To migrate:

1. Remove legacy managed files from previous versions if present and commit your cleanup.
2. Install the add-on via ddev add-on get wunderio/ddev-wunderio-drupal.
3. Verify .ddev/wunderio/custom/ overrides are preserved.

4. Commit updated .ddev/ files.

5. Import database:

   ddev import-db --file=some-sql-or-sql.gz.file.sql.gz
   

   or install site:

   ddev drush si
   

6. Create admin link and login:

   ddev drush uli
   

Performance Optimization

Database Dumps Directory (macOS)

Store database dump files in the database_dumps/ directory at the project root. On macOS this directory is excluded from Mutagen sync, avoiding slow DDEV startups and disk bloat.

Configured via upload_dirs in .ddev/config.wunderio.yaml:

upload_dirs:
  - ../database_dumps

ddev syncdb uses this directory automatically. For manual imports:

ddev import-db --file=database_dumps/my-database-backup.sql.gz

Note: On Linux (no Mutagen) this has no performance effect, but keeps dumps organized consistently across teams.