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

1. Commit .ddev/config.yaml - Share config with team
2. Use ddev composer instead of local composer
3. Don't commit database snapshots - Too large
4. Create snapshots before risky operations
5. Disable Xdebug when not debugging - Performance impact
6. Use mutagen on macOS - Much faster file sync
7. Regular ddev poweroff - Free up system resources
8. Version pin services - PHP, database, Node.js
9. Use hooks for automation - Post-start tasks
10. 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