ddev-expert

DDEV 開発エキスパート

PHP プロジェクト向けの Docker ベースのローカル開発環境、DDEV のエキスパートです。

基本概念

DDEV は、一貫性のあるコンテナ化されたローカル開発環境を提供します。以下の機能が含まれます。

• PHP、Web サーバー、データベースのコンテナを事前設定
• mkcert による HTTPS の自動設定
• Composer と Node.js の組み込みサポート
• 複数プロジェクトを簡単に管理

注: Drush はデフォルトでは含まれていません。Drupal プロジェクトの作成後に composer require drush/drush を実行する必要があります。

基本コマンド

プロジェクト管理

ddev start          # Start project containers
ddev stop           # Stop project containers
ddev restart        # Restart containers
ddev poweroff       # Stop all DDEV projects
ddev delete         # Remove project (keeps files)

コマンドの実行

ddev drush <cmd>    # Run Drush commands
ddev composer <cmd> # Run Composer
ddev php <script>   # Run PHP scripts
ddev exec <cmd>     # Run any command in web container
ddev ssh            # SSH into web container

データベース

ddev mysql          # MySQL CLI
ddev export-db      # Export database
ddev import-db      # Import database (--file=dump.sql)
ddev snapshot       # Create database snapshot
ddev restore        # Restore from snapshot

ユーティリティ

ddev describe       # Show project info and URLs
ddev logs           # View container logs
ddev launch         # Open site in browser
ddev share          # Create public URL (ngrok)

設定

.ddev/config.yaml

name: my-project
type: drupal           # Auto-detects Drupal version, or use drupal11/drupal10
docroot: web
php_version: "8.3"     # Use 8.3 for Drupal 11, 8.2 for Drupal 10
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.11"

# Additional hostnames
additional_hostnames:
  - api.my-project.ddev.site

# Extra PHP packages
webimage_extra_packages: [php8.3-imagick]

一般的なカスタマイズ

カスタムサービス（.ddev/docker-compose.*.yaml）：

version: '3.6'
services:
  redis:
    image: redis:7
    container_name: ddev-${DDEV_SITENAME}-redis
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
    expose:
      - "6379"

PHP のオーバーライド（.ddev/php/my-settings.ini）：

memory_limit = 512M
upload_max_filesize = 64M
post_max_size = 64M

Nginx の設定（.ddev/nginx_full/nginx-site.conf）： 特殊なルーティングが必要な場合に、Nginx の設定をカスタマイズします。

Drupal 固有の設定

新しい Drupal 11 プロジェクト

mkdir my-drupal && cd my-drupal
ddev config --project-type=drupal --docroot=web --php-version=8.3
ddev start
ddev composer create-project drupal/recommended-project:^11
ddev composer require drush/drush
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch

重要な注意事項：

• ddev composer create-project を実行するには、ディレクトリが空である必要があります。既存のファイル（.claude/ など）を先に別の場所に移動し、作成後に戻してください。
• Drush は Drupal 11 の recommended-project に含まれていません。必ず別途インストールしてください。
• --project-type=drupal（バージョンを自動検出）または drupal11 を明示的に指定してください。

新しい Drupal 10 プロジェクト

mkdir my-drupal && cd my-drupal
ddev config --project-type=drupal --docroot=web --php-version=8.2
ddev start
ddev composer create-project drupal/recommended-project:^10
ddev composer require drush/drush
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch

既存の Drupal プロジェクト

cd existing-project
ddev config --project-type=drupal --docroot=web
ddev start
ddev composer install
ddev import-db --file=database.sql.gz
ddev drush cr

トラブルシューティング

よくある問題

ddev composer create-project が「not allowed to be present」というエラーで失敗する場合：

# This happens when extra directories exist (like .claude/, .git/, etc.)
# Solution: Move them out temporarily
mv .claude /tmp/claude-backup
mv .git /tmp/git-backup
ddev composer create-project drupal/recommended-project:^11
mv /tmp/claude-backup .claude
mv /tmp/git-backup .git

ポートの競合：

ddev poweroff
# Check what's using ports 80/443
sudo lsof -i :80

コンテナの問題：

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

データベース接続の問題：

• ホスト：db（コンテナ内）、または 127.0.0.1:PORT（コンテナ外）
• ddev describe でポートを確認してください

権限の問題：

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

デバッグに役立つコマンド

ddev debug capabilities  # Show DDEV capabilities
ddev debug router       # Show router status
ddev logs -f            # Follow logs
ddev exec env           # Show environment variables

複数環境でのワークフロー

ddev pull の使用

.ddev/providers/ でプロバイダーを設定します。

# .ddev/providers/platform.yaml
environment_variables:
  project: my-project
  environment: main

db_pull_command:
  command: platform db:dump -e ${environment}

次に、ddev pull platform を実行します。

Xdebug の設定

Xdebug を有効にする

ddev xdebug on           # Enable step debugging
ddev xdebug off          # Disable (faster performance)
ddev xdebug status       # Check current state

IDE の設定

VS Code（PHP Debug 拡張機能を使用）：

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

PHPStorm：

1. Settings → PHP → Servers
2. サーバーを追加します。名前は DDEV プロジェクト名と一致させます。
3. Host：<project>.ddev.site、Port：443、HTTPS
4. パスマッピング：プロジェクトのルート → /var/www/html

Xdebug のモード

# .ddev/php/xdebug.ini
[xdebug]
xdebug.mode=debug,develop,coverage

モード：debug（ステップデバッグ）、develop（エラー情報の拡充）、coverage（コードカバレッジ）、profile（プロファイリング）

カスタムサービス

Redis

# .ddev/docker-compose.redis.yaml
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"
    volumes:
      - redis-data:/data

volumes:
  redis-data:

Drupal の settings.php：

$settings['redis.connection']['host'] = 'redis';
$settings['redis.connection']['port'] = 6379;
$settings['cache']['default'] = 'cache.backend.redis';

Solr

# .ddev/docker-compose.solr.yaml
services:
  solr:
    image: solr:9
    container_name: ddev-${DDEV_SITENAME}-solr
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    expose:
      - "8983"
    volumes:
      - solr-data:/var/solr
    command: solr-precreate drupal

volumes:
  solr-data:

Solr へのアクセス：ddev describe に URL が表示されます。通常は https://<project>.ddev.site:8983 です。

Elasticsearch

# .ddev/docker-compose.elasticsearch.yaml
services:
  elasticsearch:
    image: elasticsearch:8.11.0
    container_name: ddev-${DDEV_SITENAME}-elasticsearch
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    expose:
      - "9200"
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data

volumes:
  elasticsearch-data:

Mailpit（メールテスト）

DDEV には Mailpit がデフォルトで含まれています。

ddev launch -m           # Open Mailpit UI

送信メールはすべて https://<project>.ddev.site:8026 で受信されます。

パフォーマンスの調整

Mutagen（macOS/Windows）

Mutagen は、パフォーマンスを向上させる高速なファイル同期を提供します。

# Enable globally
ddev config global --mutagen-enabled

# Or per-project in .ddev/config.yaml
mutagen_enabled: true

Mutagen を使用する場面：

• 大規模なコードベース（vendor、node_modules）がある macOS
• WSL2 を使用する Windows
• ファイル I/O が遅いプロジェクト

Mutagen のコマンド：

ddev mutagen status      # Check sync status
ddev mutagen sync        # Force sync
ddev mutagen reset       # Reset if issues

NFS（macOS 向けの代替手段）

Mutagen を使わない macOS の場合：

ddev config global --nfs-mount-enabled

パフォーマンスに関するヒント

1. 同期対象から不要なファイルを除外します。

   # .ddev/config.yaml
   upload_dirs:
     - sites/default/files
   

2. 一時ファイルにtmpfs を使用します。

   # .ddev/docker-compose.performance.yaml
   services:
     web:
       tmpfs:
         - /tmp
   

3. 大規模な処理ではPHP のメモリを増やします。

   # .ddev/php/performance.ini
   memory_limit = 1024M
   

カスタム DDEV コマンド

.ddev/commands/ にプロジェクト固有のコマンドを作成します。

# .ddev/commands/web/refresh
#!/bin/bash

## Description: Full site refresh (db + config + cache)
## Usage: refresh
## Example: ddev refresh

set -e

echo "Importing database..."
drush sql:drop -y
drush sql:cli < /var/www/html/reference.sql

echo "Importing config..."
drush config:import -y

echo "Running updates..."
drush updatedb -y

echo "Clearing cache..."
drush cache:rebuild

echo "Done!"

実行可能にします：chmod +x .ddev/commands/web/refresh

その後、ddev refresh を実行します。

コマンドの配置場所

• .ddev/commands/web/ - Web コンテナで実行
• .ddev/commands/host/ - ホストマシンで実行
• .ddev/commands/db/ - データベースコンテナで実行

CI/CD との統合

GitHub Actions

# .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup DDEV
        uses: ddev/github-action-setup-ddev@v1

      - name: Start DDEV
        run: ddev start

      - name: Install dependencies
        run: ddev composer install

      - name: Run tests
        run: ddev exec ./vendor/bin/phpunit

GitLab CI

# .gitlab-ci.yml
test:
  image: ddev/ddev-gitpod-base:latest
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
  script:
    - ddev start
    - ddev composer install
    - ddev exec ./vendor/bin/phpunit

ベストプラクティス

1. .ddev フォルダーをコミットする（.ddev/db_snapshots を除く。.ddev/.gitignore で処理されます）
2. 個人用の上書き設定には .ddev/config.local.yaml を使用する（Git の追跡対象外です）
3. プロジェクトの README にカスタムサービスを記載する
4. リスクの高いデータベース操作の前にスナップショットを使用する
5. DDEV を最新の状態に保つ：ddev self-upgrade
6. パフォーマンスを向上させるため、macOS/Windows では Mutagen を使用する
7. 繰り返し行うタスク用にカスタムコマンドを作成する
8. 問題を早期に発見できるよう、CI で DDEV の設定をテストする