As the title suggests, we will be exploring the proper way of creating a custom module. But let me set your expectations before we start. This blog post is assuming you already have a broad understanding of PHP and how it works. For those of you coming here not knowing what OOP means, then this article may not be suitable for you. To know more about PHP visit this external link. The focus of this article is not about creating the module itself and its functionality but about having a standard for Drupal developers. Standards make Drupal development clean and easy to delegate and troubleshoot.
Imagine receiving a Drupal maintenance project created by another developer who does not know about Drupal standards. You’ll have to spend days looking for the custom module and much worse, the project has been passed on to 3 different developers before it got to you and your task involves modifying all of the custom modules they created. Don’t be like those developers, follow the standard!
The appropriate directory for your custom module
Before you start creating a directory for your module, you must already have a directory name in mind. Naming is important in Drupal development. The module name you will choose will be used as the machine name or unique identifier for your module so choose wisely.
To help you choose the appropriate name, below are some rules and considerations you must make.
- Select a name that is related to the function of the module
- The module name must be unique on this project [our custom modules usually start with cs_*]
- The module machine name must start with a letter
- Space is not accepted in the machine name
- It should not be any of the reserved terms : src, lib, vendor, assets, css, files, images, js, misc, templates, includes, fixtures, Drupal.
- And it must be all lowercase letters
- Underscores are accepted
Now that we have the name prepared, let’s start by going to the modules directory of your project and create a folder named “custom”. Inside the custom module directory is where we will place our module folder. The path would look like this : /modules/custom/cs_sword_art_api
The actual custom module folder does not have to be the same as the machine name so you can name it the way you want. But it is necessary to use the machine name within the module’s code and file names.
If you are planning to create contributed modules however, the path will contrib instead of custom.
Give Drupal some information about your module
Now that we have our custom module directory created, let’s create the first file that’s essential for our custom module. This is the part where we use the machine name to create an info.yml file. Go ahead and create the file as shown in the example below.
Filename : cs_sword_art_api.info.yml
Path : /modules/custom/cs_sword_art_api/cs_sword_art_api.info.yml
Why do we say this file is essential?
This file tells Drupal it’s existence and it’s not limited to custom modules. It’s also used in themes and install profiles. This file also allows Drupal to differentiate between themes and modules. Another use of this file is to provide information for the Drupal Web UI administration pages. This is the file where you provide criteria to control module activation and deactivation and Drupal version compatibility.
Below is the basic content of this file :
name: Sword Art API
description: Creates an API connector for the Sword Art Database Characters.
For more information on what you can declare in this file, visit this link : https://www.drupal.org/docs/creating-custom-modules/let-drupal-know-about-your-module-with-an-infoyml-file
Having the above is all you need to be able to enable your module without breaking your site but there’s a lot more other files you might need depending on your purpose. Below are some of the files you might need and what they are commonly used for.
- This is where hooks and theming information are usually stored
- For more information about hooks, visit this link
- This file serves as a replacement for the hook_menu() call where you can specify different routes for your module
- While the routing file creates a page at /admin/config/development/your_route_name, the definitions inside links.menu.yml are needed to add the pages to the Administration menu.
- For more information about the libraries.yml file, click here
- This is a simpler alternative to hook_permission() where you can declare permissions for your module
The information above only contains the most used parts and there are a lot more files and techniques you can use to build your very own awesome module. To learn more about in-depth module creation, see this article from Drupal.org.