How to Create a Custom Drupal Module

Drupal is a powerful and flexible content management system (CMS) that allows users to create highly customizable websites. One of its key strengths is the ability to extend its functionality through custom modules. If you're looking to create a custom module for your Drupal site, understanding how to do so can greatly enhance your website's capabilities.

In this guide, we will walk you through the process of creating a custom Drupal module that can add new features, enhance existing functionality, or integrate with other services. Whether you're hosting your Drupal site on a server through colocation or using a hosting provider, this process remains largely the same.

Understand the Basic Structure of a Drupal Module

Before you start building your module, it's important to understand the basic structure of a Drupal module. A custom module typically includes the following files:

my_module.module: This is the main PHP file that contains the core logic of your module.

my_module.info.yml: This YAML file provides Drupal with information about the module, such as its name, description, and dependencies.

my_module.install: If your module requires database schema changes or initial setup steps, this file contains the installation logic.

my_module.routing.yml: If your module adds routes to the site, this file defines them.

The module is usually placed in the /modules/custom directory of your Drupal installation.

Create the Module Directory

To get started, create a directory for your custom module in the /modules/custom directory of your Drupal installation. For example, if you are creating a module called "My Custom Module," the path would look like:

/modules/custom/my_custom_module/

Create the .info.yml File

The .info.yml file is essential for Drupal to recognize your custom module. This file should include metadata such as the module’s name, description, dependencies, and core version. Here's an example:

name: 'My Custom Module'

type: module

description: 'A custom module to add new features.'

core_version_requirement: ^8 || ^9

package: Custom

dependencies:

  - drupal:core

This file provides basic details about the module and tells Drupal which version of the core it is compatible with.

Write the Module Code in the .module File

The .module file contains the core logic of your custom module. This is where you define the functions and hooks that will extend Drupal’s functionality. For example, to implement a simple hook that runs when a node is saved, you can write the following code in the my_custom_module.module file:

/**

 * Implements hook_node_insert().

 */

function my_custom_module_node_insert($node) {

  \Drupal::logger('my_custom_module')->notice('Node created: @title', ['@title' => $node->getTitle()]);

}

This function logs a message every time a node is created on your site.

Define Routes (Optional)

If your module adds custom pages or routes to your site, you will need to define them in the .routing.yml file. For example, to add a simple page route, create the file my_custom_module.routing.yml in the module directory:

my_custom_module.page:

  path: '/custom-page'

  defaults:

    _controller: '\Drupal\my_custom_module\Controller\MyCustomPageController::content'

    _title: 'Custom Page'

  requirements:

    _permission: 'access content'

In this example, the route will map to a controller MyCustomPageController which will render the content for the custom page.

Create the Controller (If Applicable)

If your module has custom routes, you will need to create a controller that defines the content or behavior of those pages. Create a directory /src/Controller inside your module directory, and then create a PHP file with your controller logic:

namespace Drupal\my_custom_module\Controller;

use Drupal\Core\Controller\ControllerBase;

class MyCustomPageController extends ControllerBase {

  public function content() {

    return [

      '#markup' => 'Welcome to my custom page!',

    ];

  }

}

This simple controller returns a basic markup string for the page at /custom-page.

Enable the Module

Once you have created your custom module, the next step is to enable it. This can be done through Drupal's administrative interface or via Drush (if you have Drush installed on your server or hosting environment).

Via the Drupal Admin Interface: Go to Extend in the Drupal admin menu, find your module in the list, and check the box next to it. Then click Install.

Via Drush: Run the following command from the command line:
drush en my_custom_module

This command will enable the module and make it active on your Drupal site.

Test the Module

Once your module is enabled, it’s important to test it to ensure it behaves as expected. Check if the custom page is accessible, verify that hooks are firing as intended, and ensure there are no errors in the logs.

Testing can be done in a development environment before deploying to a live site, which is especially important if your Drupal site is hosted on a server or using colocation services to ensure optimal performance.

Maintain and Update the Module

After successfully creating and enabling your custom Drupal module, it's essential to keep it up to date. Monitor for any issues, bugs, or compatibility problems with new Drupal core updates. Additionally, consider adding more features or functionality as your site's requirements evolve.

Conclusion

Creating a custom Drupal module can significantly enhance the functionality of your site. By following the steps outlined above, you can create a module that integrates seamlessly into your Drupal environment. Whether your website is hosted on a server through colocation or using a standard cloud hosting provider, understanding how to build and manage custom modules is an important skill for any Drupal developer. With a custom module, you can take full advantage of Drupal’s flexibility, ensuring that your site continues to meet your unique needs as it grows.