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

Initialize your Drupal 10 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=drupal10 --docroot=web --project-name=example.com
```

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

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

Optionally if you have GrumPHP installed, update grumphp.yml:

grumphp:
  git_hook_variables:
    EXEC_GRUMPHP_COMMAND: 'ddev php'

and then re-init the hook:

ddev grumphp git:init

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 --update

Features

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 module in the said directory.
```
ddev phpstan analyze <directory-or-module-to-be-scanned>
```

syncdb: Synchronizes local database from desired environment. You should have aliases set in drush/sites/self.site.yml

ddev syncdb      # Will give error as environment is not set
ddev syncdb prod # Will fetch database from production.

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
```

Enhanced Configuration

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

Automated Workflows

The project includes several automated workflows:

Database Management
- Post-import database hooks (clears cache, sanitizes database)
- Post-restore snapshot hooks (clears cache, sanitizes database)
- Database synchronization from production
Development Environment Setup
- Automatic composer installation on first start
- Post-start hook that run drush uli
- Integration with Wunderio’s development tools eg 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:

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

Import database:

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

or install site:

ddev drush si

Create admin link and login:
```
ddev drush uli
```

Performance Optimization

Database Operations for Mac Users

Important for Mac users: When working with database imports and exports on macOS, you should store your database dump files in the database_dumps directory at the project root. This directory is specially configured in this template to provide specific performance benefits.

project-root/
├── database_dumps/    <- Place your .sql or .sql.gz files here
├── web/
├── .ddev/
└── ...

Key benefits:

Faster DDEV startup times: When large database files are stored in the standard project directories, they can significantly slow down DDEV startup as Mutagen indexes and syncs these files. Using the database_dumps directory avoids this overhead.
Reduced virtual disk usage: By excluding database dumps from Mutagen synchronization, your virtual disk requires less space, preventing potential disk space issues.

This optimization is configured via upload_dirs in .ddev/config.wunderio.yaml:

upload_dirs:
  - ../database_dumps

Example usage:

# Save your database dumps to the database_dumps directory
cp ~/Downloads/my-database-backup.sql.gz ./database_dumps/

# Then import using the path relative to your project
ddev import-db --file=database_dumps/my-database-backup.sql.gz

This improvement is particularly noticeable in projects with multiple or large database dumps, where startup times can be reduced from minutes to seconds.

Note for Linux users: While this configuration doesn’t provide performance improvements on Linux systems (which don’t use Mutagen), it’s still good practice to store database dumps in the dedicated database_dumps folder for consistent organization across team environments.