DDEV for Drupal Development

Comprehensive patterns for using DDEV as your local Drupal development environment, including setup, configuration, workflow optimization, and troubleshooting.

When This Skill Activates

Activates when working with DDEV local development including:

• DDEV configuration (.ddev/config.yaml)

• Local environment setup and management

• Database import/export operations

• Drush integration

• Xdebug and debugging tools

• Performance optimization

• Multi-site and custom commands

Available Topics

Core Setup

• @references/installation.md - Installing and configuring DDEV

• @references/config-yaml.md - .ddev/config.yaml reference

• @references/commands.md - Essential DDEV commands

Database Operations

• @references/database.md - Import, export, and snapshot workflows

• @references/drush.md - Using Drush with DDEV

Development Tools

• @references/xdebug.md - Debugging with Xdebug

• @references/mailhog.md - Email testing with MailHog

• @references/solr.md - Local Solr search setup

Advanced

• @references/custom-commands.md - Creating project-specific commands

• @references/hooks.md - Pre/post hooks automation

• @references/performance.md - Optimizing DDEV performance

• @references/multisite.md - Multi-site configuration

See /references/ directory for complete documentation.

Quick Reference

Essential Commands

Start project

ddev start

Stop project

ddev stop

Restart services

ddev restart

SSH into web container

ddev ssh

Run Drush commands

ddev drush cr ddev drush status ddev drush config:status

Run Composer

ddev composer require drupal/module_name ddev composer update

Database operations

ddev import-db --file=backup.sql.gz ddev export-db --file=backup.sql.gz ddev snapshot

View logs

ddev logs ddev logs -f # Follow mode

Describe project

ddev describe

Access URLs

ddev launch # Open site in browser

Basic .ddev/config.yaml

name: myproject type: drupal10 docroot: web php_version: "8.3" webserver_type: nginx-fpm database: type: mariadb version: "10.6" nodejs_version: "20"

Additional services

additional_services:

• solr

Custom upload/execution limits

upload_dirs:

• web/sites/default/files

Performance settings

performance_mode: mutagen # For macOS

Common Workflows

New Drupal Project

Create project directory

mkdir myproject && cd myproject

Initialize DDEV

ddev config --project-type=drupal10 --docroot=web --php-version=8.3

Install Drupal via Composer

ddev composer create drupal/recommended-project

Install Drush

ddev composer require drush/drush

Start DDEV

ddev start

Install Drupal

ddev drush site:install standard --site-name="My Site" --account-name=admin

Launch site

ddev launch

Import Existing Project

Clone repository

git clone repo-url myproject && cd myproject

Start DDEV (reads .ddev/config.yaml)

ddev start

Install dependencies

ddev composer install

Import database

ddev import-db --file=path/to/backup.sql.gz

Import files (if needed)

ddev import-files --source=/path/to/files

Run updates

ddev drush updb -y ddev drush cr

Launch

ddev launch

Database Sync from Remote

Get database backup from remote server

Method 1: Via SSH and drush sql-dump

ssh user@remote.server "cd /path/to/drupal && drush sql-dump --gzip" > backup.sql.gz

Method 2: Via platform-specific tools or download existing backup

(depends on your hosting platform)

Import to local DDEV

ddev import-db --file=backup.sql.gz

Run updates

ddev drush updb -y ddev drush cr

Sanitize for local development (optional)

ddev drush sql-sanitize -y

Daily Development Workflow

Morning: Start project

ddev start

Pull latest code

git pull origin main

Update dependencies if needed

ddev composer install

Clear cache

ddev drush cr

Work on features...

Create database snapshot before testing

ddev snapshot --name=before-testing

Test changes...

If needed, restore snapshot

ddev snapshot restore --name=before-testing

Evening: Stop project

ddev stop

Debugging with Xdebug

Enable Xdebug

ddev xdebug on

Run your debugger in IDE (PHPStorm, VSCode)

Set breakpoints and refresh page

Disable when done (improves performance)

ddev xdebug off

Check Xdebug status

ddev xdebug status

VSCode launch.json:

{ "name": "Listen for Xdebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/var/www/html": "${workspaceFolder}" } }

Performance Optimization

macOS Performance (Mutagen)

.ddev/config.yaml

performance_mode: mutagen

Restart after config change

ddev restart

NFS Mount (Alternative for macOS)

.ddev/config.yaml

nfs_mount_enabled: true

Database Tuning

.ddev/config.yaml

database: type: mariadb version: "10.6"

Create .ddev/mysql/my.cnf

[mysqld] innodb_buffer_pool_size = 512M innodb_log_file_size = 128M

Custom Commands

Create project-specific commands in .ddev/commands/web/ :

Example: .ddev/commands/web/fresh-install

#!/bin/bash

Description: Fresh Drupal install from scratch

Usage: fresh-install

Example: ddev fresh-install

set -e

echo "Installing fresh Drupal site..."

Drop existing database

drush sql-drop -y

Install Drupal

drush site:install standard
--site-name="My Site"
--account-name=admin
--account-pass=admin
-y

Import config if exists

if [ -d /var/www/html/config/default ]; then drush config:import -y fi

Clear cache

drush cr

echo "Fresh install complete!" echo "Login: admin / admin"

Make it executable:

chmod +x .ddev/commands/web/fresh-install ddev fresh-install

Best Practices

• Commit .ddev/config.yaml - Share config with team

• Use ddev composer instead of local composer

• Don't commit database snapshots - Too large

• Create snapshots before risky operations

• Disable Xdebug when not debugging - Performance impact

• Use mutagen on macOS - Much faster file sync

• Regular ddev poweroff - Free up system resources

• Version pin services - PHP, database, Node.js

• Use hooks for automation - Post-start tasks

• Document custom commands - Help team members

Common Issues

Site Not Loading

Restart project

ddev restart

Check status

ddev describe

View logs

ddev logs

Clear Drupal cache

ddev drush cr

Database Connection Error

Check database is running

ddev describe

Verify settings.php or settings.ddev.php exists

ddev ssh ls web/sites/default/settings*.php

Port Conflicts

Stop all DDEV projects

ddev poweroff

Check for port conflicts

lsof -i :80 -i :443

Change router HTTP port if needed

ddev config --router-http-port=8080 --router-https-port=8443

Slow Performance on macOS

Enable mutagen

ddev config --performance-mode=mutagen ddev restart

Or use NFS

ddev config --nfs-mount-enabled=true ddev restart

Multi-Project Management

List all projects

ddev list

Stop all projects

ddev poweroff

Remove stopped projects

ddev delete <project-name>

Remove all project containers (keep files)

ddev delete --omit-snapshot --yes <project-name>

Related Skills

• @drupal-config-mgmt - Config management workflows

• @drupal-contrib-mgmt - Module management with Composer

• @drupal-at-your-fingertips - General Drupal patterns

Official Documentation: https://ddev.readthedocs.io Drupal DDEV Quickstart: https://ddev.readthedocs.io/en/stable/users/quickstart/ Community Support: https://discord.gg/5wjP76mBJD