# DDEV Commands Reference

Comprehensive DDEV command reference for Drupal development. DDEV is a Docker-based local development environment.

## Project Initialization

```bash
# Initialize DDEV in current directory
ddev config

# Initialize with Drupal specific settings
ddev config --project-type=drupal10 --docroot=web --create-docroot

# Initialize Drupal 9
ddev config --project-type=drupal9 --docroot=web

# Initialize Drupal 11
ddev config --project-type=drupal --docroot=web

# Configure project name and PHP version
ddev config --project-name=myproject --php-version=8.2
```

## Project Management

```bash
# Start project
ddev start

# Stop project
ddev stop

# Restart project
ddev restart

# Delete project (keeps files, removes containers)
ddev delete

# Delete project and remove images
ddev delete --omit-snapshot

# Power off all DDEV projects
ddev poweroff

# Show project description
ddev describe

# List all DDEV projects
ddev list
```

## Accessing Services

```bash
# SSH into web container
ddev ssh

# SSH into database container
ddev ssh -s db

# Open project in browser
ddev launch

# Open specific path
ddev launch /admin

# Open phpMyAdmin
ddev launch -p

# Open MailHog (email catcher)
ddev launch -m
```

## Database Operations

```bash
# Import database from file
ddev import-db --src=dump.sql
ddev import-db --src=dump.sql.gz
ddev import-db --file=dump.sql

# Export database to file
ddev export-db --file=backup.sql
ddev export-db --file=backup.sql.gz --gzip

# Execute MySQL query
ddev mysql -e "SELECT * FROM users WHERE uid=1;"

# Connect to MySQL CLI
ddev mysql

# Import database and files from @drush-alias
ddev pull @production

# Snapshot database (backup)
ddev snapshot

# Restore from snapshot
ddev snapshot restore

# List snapshots
ddev snapshot list

# Delete snapshot
ddev snapshot delete --name=backup-name
```

## File Management

```bash
# Import files directory
ddev import-files --src=/path/to/files

# Pull files from remote using Drush alias
ddev pull @production --skip-db

# SCP files into container
ddev scp local-file.txt :/var/www/html/web/

# SCP files from container
ddev scp :/var/www/html/web/file.txt ./local-file.txt
```

## Composer

```bash
# Run composer install
ddev composer install

# Require package
ddev composer require drupal/webform

# Require dev package
ddev composer require --dev drupal/devel

# Update packages
ddev composer update

# Remove package
ddev composer remove drupal/old_module

# Show installed packages
ddev composer show
```

## Drush Integration

```bash
# Run Drush commands
ddev drush status
ddev drush cr
ddev drush uli

# Config import
ddev drush cim -y

# Config export
ddev drush cex -y

# Update database
ddev drush updb -y

# Enable module
ddev drush en mymodule -y

# Install Drupal
ddev drush site:install standard --account-name=admin --account-pass=admin
```

## Logs & Debugging

```bash
# View container logs
ddev logs

# Follow logs in real-time
ddev logs -f

# View web server logs
ddev logs -s web

# View database logs
ddev logs -s db

# Enable Xdebug
ddev xdebug on

# Disable Xdebug
ddev xdebug off

# Toggle Xdebug
ddev xdebug toggle

# Check Xdebug status
ddev xdebug status
```

## Mailhog (Email Testing)

```bash
# Launch MailHog UI
ddev launch -m

# All emails sent by Drupal are caught in MailHog
# Access at: http://<project>.ddev.site:8025
```

## Custom Commands

```bash
# Execute arbitrary command in web container
ddev exec ls -la

# Run PHP command
ddev exec php -v

# Run npm
ddev exec npm install
ddev exec npm run build

# Execute command in specific service
ddev exec -s db mysql --version
```

## Add-ons & Services

```bash
# Get additional services (Redis, Elasticsearch, etc.)
ddev get ddev/ddev-redis
ddev get ddev/ddev-elasticsearch
ddev get ddev/ddev-solr

# List available add-ons
ddev get --list

# Remove add-on
ddev get --remove ddev/ddev-redis
```

## Environment & Configuration

```bash
# Show DDEV version
ddev version

# Show project info
ddev describe

# Edit project configuration
# Edit .ddev/config.yaml manually

# Common config.yaml settings:
# - php_version: "8.2"
# - nodejs_version: "18"
# - webserver_type: nginx-fpm
# - database: mariadb:10.11
# - router_http_port: "80"
# - router_https_port: "443"
```

## Multiple PHP Versions

```bash
# Set PHP version
ddev config --php-version=8.1
ddev config --php-version=8.2
ddev config --php-version=8.3

# Apply changes
ddev restart
```

## Database Types & Versions

```bash
# Use MySQL
ddev config --database=mysql:8.0

# Use MariaDB (default)
ddev config --database=mariadb:10.11

# Use PostgreSQL
ddev config --database=postgres:14
```

## Performance Optimization

```bash
# Use Mutagen for better file sync performance (Mac)
ddev config --mutagen-enabled

# Use NFS for better performance (Mac/Linux)
ddev config --nfs-mount-enabled

# Disable NFS
ddev config --nfs-mount-enabled=false
```

## Sharing Your Project

```bash
# Share project via ngrok (requires ngrok account)
ddev share

# This creates a public URL for your local site
```

## Drupal-Specific Workflows

### Fresh Drupal Installation
```bash
# Initialize DDEV
ddev config --project-type=drupal10 --docroot=web

# Start DDEV
ddev start

# Install Drupal via Composer
ddev composer create drupal/recommended-project

# Install Drupal
ddev drush site:install standard --account-name=admin --account-pass=admin

# Launch site
ddev launch
```

### Clone Existing Project
```bash
# Clone repository
git clone <repo-url> myproject
cd myproject

# Start DDEV (uses existing .ddev/config.yaml)
ddev start

# Install dependencies
ddev composer install

# Import database
ddev import-db --src=database.sql.gz

# Import files
ddev import-files --src=files.tar.gz

# Clear cache
ddev drush cr

# Launch site
ddev launch
```

### Development Workflow
```bash
# Start work
ddev start

# Enable development modules
ddev drush en devel devel_generate -y

# Watch theme files (if using compile tools)
ddev exec npm run watch

# Clear cache frequently
ddev drush cr

# Stop work
ddev stop
```

## Troubleshooting

```bash
# Restart if containers are unresponsive
ddev restart

# Clean restart (rebuild containers)
ddev restart --clean

# Remove all Docker volumes and restart
ddev stop --remove-data
ddev start

# Check for port conflicts
ddev describe

# View detailed debug info
ddev debug test

# Check Docker is running
docker ps

# Rebuild DDEV containers from scratch
ddev delete --omit-snapshot
ddev start
```

## Common Issues

### Port Conflicts
If ports 80/443 are in use:
```bash
# Change router ports in .ddev/config.yaml
router_http_port: "8080"
router_https_port: "8443"

# Then restart
ddev restart
```

### Permission Issues
```bash
# Fix file permissions
ddev exec chmod -R 755 web/sites/default/files

# Fix ownership
ddev exec chown -R www-data:www-data web/sites/default/files
```

### Database Connection Issues
Check database credentials in settings.php or settings.ddev.php:
```php
$databases['default']['default'] = [
  'database' => 'db',
  'username' => 'db',
  'password' => 'db',
  'host' => 'db',
  'port' => '3306',
  'driver' => 'mysql',
];
```

## Best Practices

1. **Always use `ddev` prefix**: Run Composer, Drush, and other tools through DDEV (`ddev composer`, `ddev drush`)
2. **Commit .ddev/config.yaml**: Share project configuration with team
3. **Use .gitignore**: Exclude `.ddev/.importdb`, `.ddev/.ddev-docker-compose*`
4. **Performance**: Enable Mutagen or NFS on Mac for better performance
5. **Xdebug**: Only enable when needed (slows performance)
6. **Regular updates**: Keep DDEV updated with `brew upgrade ddev` (Mac) or equivalent
7. **Clean shutdown**: Use `ddev stop` before system shutdown
8. **Database snapshots**: Create snapshots before major changes
9. **Environment variables**: Use `.ddev/config.yaml` for environment-specific settings
10. **Multiple projects**: Use unique project names to avoid conflicts

## Additional Resources

- Official docs: https://ddev.readthedocs.io/
- DDEV Discord: https://discord.gg/hCZFfAMc5k
- DDEV GitHub: https://github.com/ddev/ddev