Drupal Module Development

When to use

• The user wants to implement a Drupal hook such as hook_form_alter or hook_theme in a custom module .module file.
• The user wants to scaffold a new custom Drupal module with an .info.yml manifest and a service or hook.
• The user needs to register a service in a Drupal module .services.yml and inject dependencies into it.

When NOT to use

• Do not build a custom Drupal module when a maintained contrib module on drupal.org already covers the requirement.
• Do not use a module when the task is purely Twig templates, CSS, or JavaScript; that belongs in a Drupal theme.

Core guidance

• Declare type, core_version_requirement, and dependencies in .info.yml — In my_module.info.yml set type: module, core_version_requirement: ^10 || ^11, and list each module dependency as drupal:node or project:module.
• Match the machine name across file names and namespace — Use one lowercase, underscore machine name (e.g. my_module) for the directory, the .info.yml, the .module file, and map it to the Drupal\my_module PSR-4 namespace under src/.

Quick recipe

1. Create modules/custom/my_module/my_module.info.yml with name, type: module, and core_version_requirement: ^10 || ^11. (verify: The module appears at /admin/modules under its declared name.)
2. Add my_module.services.yml defining a service class under Drupal\my_module\ with its dependencies listed in arguments. (verify: drush ev can resolve the service from the container without error.)
3. Add a my_module_HOOK() implementation to my_module.module, then run drush cr so Drupal discovers it. (verify: The hook fires on the expected event after the cache rebuild.)

Best practices

• For controllers, forms, and plugins that Drupal instantiates, implement create(ContainerInterface $container) and pull dependencies from the container there rather than declaring them in a .services.yml file
• Implement hooks as functions named MACHINENAME_hookname (e.g
• Define services in my_module.services.yml with explicit arguments and inject them via the constructor; call \Drupal::service() only inside hooks and other procedural code that cannot receive injection

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. New services or hooks not picked up until cache rebuild — A newly added service, route, or hook appears to have no effect because Drupal caches its discovery data. Fix: Run drush cache:rebuild (or drush cr) after adding or renaming services, routes, or hooks.
2. Module refuses to install on unsupported core — The module is missing from the extend list or errors on install because core_version_requirement is absent or too narrow. Fix: Set core_version_requirement: ^10 || ^11 (or the range you actually support) and remove the legacy core: 8.x key.
3. Class not found due to PSR-4 namespace mismatch — A service class fails to load with a ClassNotFound error even though the file exists under src/. Fix: Ensure the namespace is exactly Drupal\MACHINENAME\... and the file path under src/ mirrors the sub-namespace.

Version notes

• core_version_requirement replaced core key in Drupal 9 (PHP >=8.1) — From Drupal 9, .info.yml must use core_version_requirement with a semver constraint; the old core: 8.x key is removed in Drupal 10.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/drupal/module-development.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: drupal/entity-api, php/typed-properties