module-scaffold

Environment

All commands run via ssh web. All modules go in $DDEV_DOCROOT/modules/custom/. Never hardcode web/ — use $DDEV_DOCROOT (detect with grep "^docroot:" .ddev/config.yaml).

Module structure

Replace every {module_name} placeholder with the module machine name (lowercase, underscores, e.g. event_manager) and {Module Name} with the human-readable name.

$DDEV_DOCROOT/modules/custom/{module_name}/
├── {module_name}.info.yml
├── {module_name}.module
├── {module_name}.services.yml
├── {module_name}.routing.yml
├── {module_name}.permissions.yml
├── {module_name}.links.menu.yml        # If admin UI needed
├── config/
│   ├── install/                        # Default config
│   └── schema/
│       └── {module_name}.schema.yml    # REQUIRED for all config
├── src/
│   ├── Controller/                     # Route controllers
│   ├── Form/                           # Config and custom forms
│   ├── Service/                        # Business logic services
│   └── Plugin/                         # Block, Field, etc.
└── tests/
    └── src/
        ├── Unit/                       # Pure logic tests
        ├── Kernel/                     # Service integration tests
        └── Functional/                 # Full browser tests

info.yml template

name: '{Module Name}'
type: module
description: '{Brief description}'
package: Custom
core_version_requirement: ^10.3 || ^11
php: 8.3
dependencies: []

services.yml template

services:
  {module_name}.{service_name}:
    class: Drupal\{module_name}\Service\{ServiceName}
    arguments:
      - '@entity_type.manager'
      - '@logger.factory'
      - '@cache.default'

Controller template

<?php

declare(strict_types=1);

namespace Drupal\{module_name}\Controller;

use Drupal\Core\Controller\ControllerBase;
use Symfony\Component\DependencyInjection\ContainerInterface;

final class {ControllerName} extends ControllerBase {

  public static function create(ContainerInterface $container): static {
    return new static(
      // Inject services here
    );
  }

  public function __construct(
    // Type-hinted constructor parameters
  ) {}

}