Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Modules and Hooks

Custom Module Basics

Write your first custom Drupal module: folder layout, the info.yml file, namespaces and PSR-4, installing with Drush, and how Drupal discovers module code.

Modules are how Drupal is extended. Core is a set of modules, contributed projects from drupal.org are modules, and the code that makes your site unique belongs in a custom module. A custom module can add pages, blocks, forms, entity types, permissions, services and more. Everything you write lives in your own files, so core updates never overwrite it.

Drupal cannot run on this site, so module code is shown read-only. The TryIt blocks are JavaScript stand-ins of the mechanisms (discovery and autoloading) so you can see what Drupal does with your files.

Where modules live

Place custom modules in modules/custom/ (Composer-based projects use web/modules/custom/). A module called tutorial_notes looks like this:

TEXT
modules/custom/tutorial_notes/
  tutorial_notes.info.yml
  tutorial_notes.module
  tutorial_notes.routing.yml
  tutorial_notes.permissions.yml
  tutorial_notes.services.yml
  src/
    Controller/NotesController.php
    Form/NoteSettingsForm.php
    Plugin/Block/RecentNotesBlock.php
  config/install/
  templates/
  tests/src/Unit/

You only create the files you need. The smallest module is a single .info.yml file.

The info file

YAML
name: Tutorial Notes
type: module
description: 'Adds a notes page and a recent notes block.'
package: Custom
core_version_requirement: ^10 || ^11
dependencies:
  - drupal:node
  - drupal:views
configure: tutorial_notes.settings
  • type: module is required. The file name is the machine name, which must be lowercase letters, digits and underscores, start with a letter, and be unique across the site.
  • dependencies uses the pattern project:module. Drupal refuses to enable the module until they are available.
  • configure is a route name that adds a Configure link on the Extend page.

Enable it with drush en tutorial_notes (alias for pm:install) or on the Extend page. Disable and delete configuration with drush pmu tutorial_notes.

Node.js Stand-in: module discovery and dependencies

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Namespaces and autoloading

Classes in src/ follow PSR-4. The namespace is Drupal\MODULE_NAME\ and the path inside src/ mirrors the rest:

PHP
<?php

namespace Drupal\tutorial_notes\Controller;

use Drupal\Core\Controller\ControllerBase;

class NotesController extends ControllerBase {

  public function overview(): array {
    return [
      '#markup' => $this->t('Hello from the notes module.'),
    ];
  }

}

This class must be in src/Controller/NotesController.php, and the file name must equal the class name. If either is wrong, Drupal cannot find the class and you see a "class not found" error. The stand-in below shows the mapping rule.

Node.js Stand-in: PSR-4 class to file path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The .module file

tutorial_notes.module holds procedural hook implementations (the next lessons explain hooks). Modern Drupal puts most logic in classes under src/ and keeps the .module file small. Never add use statements that load classes at the top of the file unless they are needed; hooks run often.

PHP
<?php

/**
 * @file
 * Hooks for the Tutorial Notes module.
 */

use Drupal\Core\Routing\RouteMatchInterface;

/**
 * Implements hook_help().
 */
function tutorial_notes_help($route_name, RouteMatchInterface $route_match) {
  if ($route_name === 'help.page.tutorial_notes') {
    return '<p>' . t('Shows notes written by editors.') . '</p>';
  }
}

Generating a module

Drush can scaffold the files, so you do not need to type boilerplate:

Terminal
drush generate module
drush generate controller
drush generate form-simple
drush generate plugin:block
drush generate service

The generators ask a few questions and write correct file names and namespaces, which is a good way to learn the layout.

Coding standards and conventions

  • Prefix functions in .module with the machine name, e.g. tutorial_notes_help.
  • Use two spaces for indentation, no tabs, and document public methods.
  • Use $this->t() or t() for user-visible strings so they can be translated.
  • Do not hack core or contributed modules; write a module that alters them with hooks, plugins or events instead.
  • Check your work with phpcs --standard=Drupal,DrupalPractice modules/custom.

Debugging first problems

  • "The website encountered an unexpected error": look at Reports > Recent log messages or drush watchdog:show --tail.
  • Module not listed: wrong folder, missing core_version_requirement, or YAML mistakes. Run drush cr after adding files.
  • Class not found: check the namespace and file path, and make sure the file name matches the class name.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a custom module's PHP class Drupal\tutorial_notes\Form\NoteForm live?

    PSR-4 maps Drupal\MODULE\ to the module's src folder.
  2. 2. Which key is mandatory in a module info file besides name?

    Drupal needs type and the supported core versions.
  3. 3. What does drush en do?

    drush en is the short form of pm:install.
  4. 4. Where should most logic of a modern module live?

    Classes are testable and autoloaded; the .module file stays small.

Summary

  • A module is a folder with NAME.info.yml in modules/custom.
  • Dependencies are written as project:module and installed first.
  • Classes live in src/ and follow PSR-4 under Drupal\NAME\.
  • Keep the .module file for hooks; use drush generate for boilerplate.
  • Read the logs when something breaks.

Next: Routes and Controllers