Introduction to Drupal Module Development

Welcome to this tutorial on Drupal module development! Drupal is a powerful open-source content management system (CMS) that's highly customizable thanks to its modular architecture. Modules are the building blocks that extend Drupal's core functionality, allowing you to add features like custom pages, blocks, forms, or integrations without altering the core code.

Developing custom modules is essential when existing contributed modules don't meet your specific needs. This introduction will cover the basics, including prerequisites, module structure, and a step-by-step guide to creating a simple "Hello World" module. We'll use Drupal 10/11 conventions (as of 2025), which emphasize object-oriented PHP, YAML configuration, and dependency injection for better maintainability.

By the end, you'll have a working module and understand the fundamentals to build more complex ones. Let's dive in!

Why Develop Drupal Modules?

• Customization: Tailor Drupal to unique project requirements, such as custom workflows or integrations.
• Reusability: Package code for reuse across sites or share with the community on drupal.org.
• Performance: Avoid overloading with unnecessary contributed modules by creating lightweight solutions.
• Learning Opportunity: Gain deeper insight into Drupal's APIs, hooks, events, and services.

Prerequisites

Before starting, ensure you have:

• Basic knowledge of PHP (object-oriented programming preferred) and YAML syntax.
• Familiarity with Drupal site building (e.g., content types, views, blocks).
• A local development environment: Use tools like Composer for dependency management, Drush/Drupal Console for CLI tasks, and a setup like Lando, DDEV, or XAMPP with MySQL/PostgreSQL.
• Drupal installed (version 10 or later recommended).
• A code editor like VS Code or PhpStorm, and Git for version control.
• Comfort with command-line basics.

If you're new to PHP, practice simple scripts first. No prior module development experience is needed!

Basic Module Structure

A Drupal module is a folder containing specific files. Place it in /modules/custom/ (or /modules/contrib/ for shared ones) to keep it organized. Key files include:

• .info.yml: Metadata file telling Drupal about your module (name, description, dependencies, core compatibility).
• .module: Optional PHP file for hooks (functions that interact with Drupal events).
• .routing.yml: Defines URL paths and maps them to controllers.
• src/ folder: Contains PHP classes like controllers, services, or plugins (follows PSR-4 standards).
• Other optional folders: config/ for default settings, templates/ for Twig templates, css/ or js/ for assets.

Here's a simple table summarizing the structure:

Step-by-Step: Creating a "Hello World" Module

Let's create a simple module that adds a custom page displaying "Hello, World!" at the URL /hello. This classic example demonstrates routing, controllers, and enabling modules.

Step 1: Create the Module Folder

• Navigate to your Drupal site's /modules/custom/ directory.
• Create a new folder named hello_world (use lowercase and underscores for machine names).

Step 2: Add the .info.yml File

• Inside hello_world/, create hello_world.info.yml.
• Add the following YAML content:

name: 'Hello World'
type: module
description: 'This is a Hello world module'
package: Custom
core_version_requirement: ^10 || ^11

This registers your module with Drupal.

Image Example: After this step, your module should appear in the admin interface at /admin/modules. (Imagine a screenshot of the Extend page listing "Hello World" under Custom packages, unchecked. Would you like me to generate this image?)

Step 3: Define a Route in .routing.yml

• Create hello_world.routing.yml in the module root.
• Add:

hello_world.hello_world_page:
  path: '/hello'
  defaults:
    _title: 'Hello World Page'
    _controller: '\Drupal\hello_world\Controller\HelloWorldPage'
  requirements:
    _permission: 'access content'

This maps /hello to a controller method and requires basic access permission.

Step 4: Create the Controller

• Create the folder structure: hello_world/src/Controller/.
• Inside it, add HelloWorldController.php with:

<?php

declare(strict_types=1);

namespace Drupal\hello_world\Controller;

use Drupal\Core\Controller\ControllerBase;

/**
 * Returns responses for Hello World routes.
 */
final class HelloWorldPage extends ControllerBase {

  /**
   * Builds the response.
   */
  public function __invoke(): array {

    $build['content'] = [
      '#type' => 'item',
      '#markup' => $this->t('It works!'),
    ];

    return $build;
  }

}

This extends Drupal's base controller and returns simple markup.

Step 5: Enable and Test the Module

• Go to /admin/modules in your Drupal site.
• Search for "Hello World", check the box, and click "Install".
• Alternatively, use Drush: drush en hello_world -y.
• Clear cache if needed: drush cr.

Visit /hello – you should see "Hello, World!".
 

Next Steps

Congratulations – you've built your first module! To expand:

• Add hooks in a .module file (e.g., alter forms).
• Include configuration or services.
• Explore advanced topics like plugins, events, or dependency injection.
• Check official docs for more tutorials, like adding blocks or forms.