DDEV + Craft CMS Plugin Scaffold

This repository demonstrates how to develop a Craft CMS plugin with Craft installed in a subdirectory while using DDEV as the local runtime.

What's different in this repo

• Plugin lives in src/: The plugin code is in src with PSR-4 autoloading (viget\\ddev\\ → src/). This matches typical Craft plugin scaffolds.

• Craft installed in craft-install/: Instead of installing Craft at the repository root, Craft is installed in the craft-install subdirectory. DDEV is configured with docroot: craft-install/web so web requests are served from craft-install/web.

• Composer path repository from Craft to repo root: In craft-install/composer.json, there is a repository entry:

  "repositories": [
    {
      "type": "composer",
      "url": "https://composer.craftcms.com",
      "canonical": false
    },
    {
      "type": "path",
      "url": "../"
    }
  ]

  • What this does: The type: path repository tells Composer (running inside craft-install/) to treat the directory one level up (../) as a Composer package source. That allows the Craft project to require and load the plugin that lives at the repository root without publishing it to Packagist. Composer installs it via a symlink, so edits in src/ are immediately reflected in Craft.

• Root-level craft CLI: A craft executable at the repo root bootstraps via craft-install/bootstrap.php and runs Craft's console application. This means ddev craft <command> works as expected since DDEV's craftcms project type automatically detects and uses it.

Project references

• Root plugin package and handle:

  {
      "name": "viget/ddev-plugin",
      "type": "craft-plugin",
      "autoload": { "psr-4": { "viget\\\\ddev\\\\": "src/" } },
      "extra": { "handle": "ddev-plugin" }
  }

• DDEV config (docroot and PHP):

  name: ddev-craft-plugin
  type: craftcms
  docroot: craft-install/web
  composer_root: "."
  php_version: "8.3"
  webserver_type: nginx-fpm

Common commands

ddev start                    # Start the environment
ddev craft help               # Run Craft CLI commands
ddev craft migrate/all        # Run migrations
ddev composer install         # Installs plugin dependencies (runs at repo root)
ddev composer install --dir craft-install  # Installs Craft app dependencies

Notes

• composer_root is set to . in .ddev/config.yaml, so ddev composer operates on the plugin's root composer.json by default. Use ddev composer install --dir craft-install when you need to update the Craft app's dependencies.
• Because the plugin is installed via a path repository, Composer links it as a symlink. Changes in src/ are available immediately without reinstalling.