Setting up the module folder structure in modules/customfor Drupal 8 , 9 , 10 , and 11

Home » Module Development » Setting up the module folder structure in modules/custom
Last updated :  
8.x , 9.x , 10.x , 11.x

Continuing our journey in Drupal module development, it's time to discuss the file structure essential for a custom module. A well-organized module structure is crucial for maintaining clarity, functionality, and scalability. By the end of this lesson, you’ll be prepared to set up the foundational folder structure for your first custom module.

Understanding the Custom Module Directory

In a Drupal installation, there are several key directories used for different purposes. Custom modules should be placed in the modules/custom directory. This not only keeps them separate from core and contributed modules but also avoids conflicts during updates.

Here's how your Drupal directory hierarchy looks:

            
 /drupal-root
   /core
   /modules
    /contrib
    /custom

The custom directory is specifically for any modules you or your team creates, thus ensuring organization and reducing errors when updates to the system are applied.

Creating Your Module's Folder Structure

Let's set up a basic folder structure for your custom module. You can follow these steps to ensure your module is organized properly:

Step 1: Create the Module Directory

Navigate to your Drupal installation's modules/custom directory. Here, create a new directory with a descriptive name for your module. For instance, if you're building a module called "Hello World", you'd create a folder named hello_world.

/drupal-root/modules/custom/hello_world

Step 2: Define Your Module Structure

Within your new module directory, you'll want to create several key files and sub-directories that will form the basic structure of your module. Here’s a typical base structure:


/hello_world
 /src
 /templates
 /config
 hello_world.info.yml
  • /src: This directory is for any PHP classes you may create.
  • /templates: Houses Twig templates for theming, a fundamental part of the Drupal theming layer.
  • /config: This directory contains configuration files that manage settings for your module across environments.

To begin with, we will focus on the creation of the hello_world.info.yml file in the next lesson, as it is necessary to register the module with Drupal.

Naming Conventions and Best Practices

Adhering to a consistent naming convention is vital in module development:

  • Lowercase Names: Directory and file names should typically be lowercase and use underscores for word separation.
  • Simplicity: Keep names short but descriptive to make it clear what your module does.
  • Uniqueness: Ensure the module name is unique across all custom and contributed modules to prevent conflicts.

Verifying Your Structure

Once your directory is set up, verify that all necessary directories and an info file placeholder (we'll populate it soon) exist. This verification is important before progressing so that Drupal can recognize and use your module.

Conclusion

You've successfully completed the setup of the folder structure for your first custom module in the modules/custom directory. This organization sets the stage for developing structured and efficient modules.

In our next session, we will focus on Creating the .info.yml file for module metadata, an essential step in informing Drupal about your new module. Stay tuned!