ddev-expert

name	ddev-expert
description	DDEV local development expertise. Use when working with DDEV projects, containers, configuration, or troubleshooting DDEV environments.

DDEV Expert

Essential Commands

# Project
ddev start | stop | restart | poweroff | delete

# Execute
ddev drush <cmd> | ddev composer <cmd> | ddev exec <cmd> | ddev ssh

# Database
ddev mysql | ddev export-db | ddev import-db --file=dump.sql
ddev snapshot | ddev restore

# Utilities
ddev describe        # URLs and project info
ddev logs -f         # Follow logs
ddev launch          # Open in browser
ddev launch -m       # Open Mailpit UI

Configuration (.ddev/config.yaml)

name: my-project
type: drupal          # auto-detects version; or drupal11/drupal10
docroot: web
php_version: "8.3"
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.11"
additional_hostnames:
  - api.my-project.ddev.site
webimage_extra_packages: [php8.3-imagick]
mutagen_enabled: true  # macOS/Windows performance

Overrides: .ddev/config.local.yaml (gitignored personal config) PHP overrides: .ddev/php/*.ini

Troubleshooting

ddev composer create-project fails ("not allowed to be present"): Move extra dirs out temporarily (.claude/, .git/), run create-project, move back.

Port conflicts:

ddev poweroff && sudo lsof -i :80

Container issues:

ddev restart
ddev debug refresh    # Rebuild containers
ddev delete && ddev start  # Nuclear option

Database: Host is db (inside container) or 127.0.0.1:PORT (outside). Check port with ddev describe.

Permissions: ddev exec chown -R $(id -u):$(id -g) .

PHP deprecation warnings in Drush — create .ddev/php/drush.ini:

[PHP]
error_reporting = 22527   ; E_ALL & ~E_DEPRECATED
display_errors = Off
log_errors = On
error_log = /tmp/php-errors.log

Docker Desktop overlay2 I/O errors — normal restart is not enough:

killall -9 Docker   # then relaunch Docker Desktop

Mutagen sync hanging after Docker crash:

ddev poweroff && ddev start
# If still stuck:
ddev stop
~/.ddev/bin/mutagen daemon stop
~/.ddev/bin/mutagen daemon start
ddev mutagen reset && ddev start

ddev mutagen status -l   # Detailed sync status
ddev mutagen monitor     # Real-time progress

Debug commands:

ddev debug capabilities | ddev debug router
ddev exec env

Xdebug

ddev xdebug on | off | status

.ddev/php/xdebug.ini:

[xdebug]
xdebug.mode=debug,develop,coverage

Modes: debug (step), develop (enhanced errors), coverage, profile. See README.md for full IDE setup (VS Code / PHPStorm).

Custom Services

Add .ddev/docker-compose.<service>.yaml. Common pattern:

services:
  redis:
    image: redis:7-alpine
    container_name: ddev-${DDEV_SITENAME}-redis
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    expose:
      - "6379"

See README.md for full Solr, Elasticsearch, Redis configs and Drupal settings.php snippets.

Custom Commands

Create .ddev/commands/web/<name> (or host/, db/):

#!/bin/bash
## Description: Full site refresh
## Usage: refresh
set -e
drush sql:drop -y && drush sql:cli < /var/www/html/reference.sql
drush config:import -y && drush updatedb -y && drush cache:rebuild

chmod +x then run as ddev <name>.

Performance (macOS/Windows)

ddev config global --mutagen-enabled   # Enable globally
ddev mutagen status | sync | reset

See README.md for NFS, tmpfs, and file sync exclusion patterns.