Getting Started with DDEV for Drupal Development

Setting up a local Drupal development environment requires tools that handle web servers, databases, and PHP configuration. DDEV provides a Docker-based solution that simplifies this process while maintaining flexibility for different project requirements.

In the video above, you’ll learn how to install and configure DDEV, create a new Drupal project, use essential commands for daily development, import and export databases, set up debugging with Xdebug, and extend DDEV with add-ons and custom commands.

Understanding DDEV

DDEV is a Docker-based PHP development environment that wraps Docker functionality into simple commands. The tool minimizes changes to your Drupal codebase, storing configuration in a dedicated .ddev folder and config.yaml file that you can commit to your repository.

Benefits of Using DDEV

DDEV provides several advantages for Drupal development:

• Consistent environments: Team members run identical configurations regardless of their operating system.
• Minimal project changes: Only a settings.ddev.php file gets added to your Drupal codebase.
• Quick setup: New developers can pull a repository and start working with a few commands.
• Version control: The .ddev folder can be committed, sharing configuration across the team.

Prerequisites

Before installing DDEV, you need Docker installed on your system. Options include:

• Docker Desktop: The standard Docker application for Mac, Windows, and Linux.
• OrbStack: An alternative container runtime for Mac users.
• Colima: An open-source container runtime option.

Installing DDEV

Mac Installation

Install DDEV using Homebrew:

brew install ddev/ddev/ddev

This command downloads and configures DDEV with all required dependencies.

Quick Start Resources

The DDEV documentation provides quick start guides for various platforms including Drupal, Drupal CMS, and older Drupal versions. These guides contain copy-paste commands for rapid project setup.

Creating a Drupal Project

Initial Configuration

Create a new project directory and configure DDEV:

mkdir drupal-crm
cd drupal-crm
ddev config --project-type=drupal11 --docroot=web

The --project-type flag sets up appropriate defaults for Drupal 11, including PHP version, web server configuration, and database settings. The --docroot flag specifies the web root directory.

NOTE: Please refer to the documentation for the latest commands.

Understanding the Configuration

The ddev config command creates a .ddev folder containing:

• config.yaml: Main configuration file controlling project name, PHP version, web server type, and database settings.
• .gitignore: Ensures only relevant configuration gets committed.
• settings.ddev.php: Auto-generated Drupal settings file (do not modify this file).

The config.yaml file allows customization of:

• PHP version: Change to match your production environment.
• Web server: Choose between nginx-fpm or Apache.
• Database type: Switch between MariaDB, MySQL, or PostgreSQL.

Installing Drupal

Start DDEV and install Drupal:

ddev start
ddev composer create-project "drupal/recommended-project:^11"
ddev composer require drush/drush
ddev drush si standard -y

The ddev prefix runs commands inside the container, ensuring access to the correct PHP version and database credentials.

Generate a login link:

ddev drush uli

Essential DDEV Commands

Project Management

Common commands for managing your DDEV project:

• ddev start: Start the project containers.
• ddev stop: Stop containers without losing data.
• ddev restart: Stop and start containers.
• ddev list: View all DDEV projects on your system.
• ddev describe: Display detailed project information including URLs and ports.
• ddev poweroff: Stop all DDEV projects and services.

Running Commands in Containers

Execute commands inside the web container:

ddev composer require drupal/admin_toolbar
ddev drush cr
ddev drush sqlc

Access the container shell directly:

ddev ssh

Access the database container:

ddev ssh -s db

Viewing Logs

Monitor container logs:

ddev logs
ddev logs -f  # Follow logs in real-time
ddev logs -s db  # Database container logs
ddev exec tail -f /var/log/nginx/access.log

Database Management

Importing Databases

Import a database dump:

ddev import-db --file=db-export-custom-site.sql.gz

DDEV handles gzipped files automatically, extracting and importing in one step.

Exporting Databases

Export the current database:

ddev export-db > db-export.sql.gz

For uncompressed exports:

ddev export-db --gzip=false > db-export.sql

Database Snapshots

Create a named snapshot:

ddev snapshot --name=before-update

List available snapshots:

ddev snapshot --list

Restore a snapshot:

ddev snapshot restore

The restore command presents an interactive list of available snapshots for selection.

Importing Files

Import the files directory:

ddev import-files --source=custom-files.zip

DDEV automatically places files in the correct location based on the project type (sites/default/files for Drupal).

IDE Integration

VS Code Setup

Install the DDEV Manager extension from the VS Code marketplace. This extension provides:

• Project status display in the sidebar.
• One-click container access.
• Direct database connections.
• Automatic Xdebug configuration.

The extension creates the necessary .vscode/launch.json and .vscode/tasks.json files for debugging.

PHPStorm Setup

Install the DDEV Integration plugin from the JetBrains marketplace. Features include:

• Terminal dropdown to SSH directly into containers.
• Automatic database connection configuration.
• Quick access to project URLs and services.
• Xdebug configuration with zero setup.

DDEV Add-ons

Browsing Available Add-ons

Visit addons.ddev.com to explore available add-ons including:

• Adminer: Web-based database management interface.
• Solr: Apache Solr search integration.
• Redis: Redis caching layer.
• Elasticsearch: Elasticsearch integration.
• Memcache: Memcached support.

Installing Add-ons

Install an add-on:

ddev addon get ddev/ddev-adminer
ddev restart

After installation, run ddev describe to see new service URLs.

Mailpit Email Capture

Drupal 11 projects include Mailpit by default. This service captures all outgoing emails, preventing test emails from reaching real addresses. Access Mailpit through the URL shown in ddev describe.

Debugging with Xdebug

Enabling Xdebug

Turn on Xdebug:

ddev xdebug on

Turn off Xdebug when not debugging (improves performance):

ddev xdebug off

PHPStorm Configuration

PHPStorm provides zero-configuration debugging with DDEV:

1. Enable Xdebug with ddev xdebug on.
2. Click Start Listening for PHP Debug Connections in PHPStorm.
3. Set breakpoints in your code.
4. Refresh the page in your browser.

VS Code Configuration

With the DDEV Manager extension installed, debugging configuration happens automatically. Without the extension, add the configuration manually through Run > Add Configuration > PHP.

To manually add debugging to VS Code without the DDEV manager, follow the documentation on the Visual Studio Code (VS Code) Debugging Setup page.

Custom Commands

Creating Custom Commands

Create reusable commands by adding shell scripts to .ddev/commands/web/:

#!/bin/bash

## Description: Fresh Drupal install
## Usage: fresh-install

drush si standard -y
drush cr
drush uli

Save this as .ddev/commands/web/fresh-install and run:

ddev fresh-install

Command Locations

Place commands in different directories based on where they run:

• .ddev/commands/web/: Run in the web container.
• .ddev/commands/host/: Run on the host machine.
• .ddev/commands/db/: Run in the database container.

Automation with Hooks

Configuring Hooks

Add hooks to config.yaml to automate tasks:

hooks:
    post-import-db:
        - exec: drush sql:sanitize
        - exec: drush updatedb
        - exec: drush cache:rebuild
    post-start:
        - composer: install
        - exec: drush user:login

Available Hook Events

Some common hook events include:

• post-start: Run after ddev start completes.
• post-import-db: Run after database import.
• pre-stop: Run before stopping containers.
• post-snapshot: Run after creating a snapshot.

Hooks reduce manual steps and ensure consistent workflows across the team.

Additional Hostnames

If you need to access your site via a different domain (e.g., mysite.ddev.site and api.mysite.ddev.site), use the additional_hostnames configuration.

ddev config --additional-hostnames drop-crm
ddev restart

This updates the router to accept traffic on the new subdomain.

Or you can manually edit the additional hostnames option in the config.yaml.

additional_hostnames:
    - drop-crm

Make sure you run ddev restart after every change.

Performance with Mutagen

DDEV uses Mutagen to sync files between the host and the container. This provides near-native file performance, even on macOS where Docker volume mounting can historically be slow.

If you encounter synchronization issues where file changes on your host do not reflect in the container, you can force a resync:

ddev mutagen sync

Alternatively, run ddev restart to reset the synchronization status.

External Database Access

Connecting Database Clients

Connect external tools like Sequel Ace or TablePlus:

1. Run ddev describe to find the database port.
2. Use localhost as the host.
3. Enter db for username, password, and database name.
4. Enter the port number from ddev describe.

The port changes each time containers start, so check ddev describe for the current value.

Summary

DDEV simplifies Drupal local development by providing a consistent, containerized environment that requires minimal configuration. Key features include:

• Simple project setup with the ddev config command and project type presets.
• Built-in services like Mailpit for email testing and support for database management tools.
• Extensibility through add-ons for services like Solr, Redis, and Elasticsearch.
• Automation with custom commands and hooks for repetitive tasks.
• IDE integration with extensions for VS Code and PHPStorm that simplify debugging.

Start with the basic setup and add features as your project requires them. The DDEV documentation provides detailed guidance for advanced configurations and troubleshooting.