Magento 2 Module Tutorial

Module Basics

The module is one of the fundamental building blocks of the Magento 2 system and represents a key point of extension for developers. Every module should contain the following:

1. Code encapsulating a unique business feature
2. A default user interface (customizable by themes)
3. Relevant blocks, controllers, models, etc.
4. Minimal dependencies

Creating a new module and enabling it will require completing a few general steps:

1. Create the module location
2. Register the module (2 files)
   • registration.php
   • etc/module.xml
3. Enable the module

Step 1 – Create the module location

Modules should be located in either the app/code or vendor folders, depending on the installation method. When building a module for a specific project (not focused on reusability and composer installation), the app/code folder location is more appropriate. This post will focus on custom modules placed in the app/code folder.

When creating a new module, strict attention must be paid to naming conventions. To begin, the module name must be in the form:

 VendorName_ModuleName

The name and folder location must match:

magento2/app/code/VendorName/ModuleName

Step 2 – Register the module

Now that our project has a location, the first step in registering a module is creating the registration.php file:

magento2/app/code/VendorName/ModuleName/registration.php

The code template for registration.php is as follows:

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    ‘VendorName_ModuleName’,
    __DIR__
);

The main components of registration.php are the register method of class ComponentRegistrar. We give this method two parameters: component type and module name. In this case the component type is as module (as opposed to a theme, language pack, or external library), and our module name is VendorName_ModuleName.

Now that we’ve told Magento the name of our module we need to provide a version number and any dependencies. This takes place in the module.xml.

First we need to add an etc folder to our project, and then within it create the module.xml file. The full path to module.xml should be:

 magento2/app/code/VendorName/ModuleName/etc/module.xml.

The basic template for module.xml is as follows:

<?xml version=”1.0”?>

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=”urn:magento:framework:Module/etc/module.xsd”>
    <module name=”VendorName_ModuleName” setup_version=”0.0.0”>
        <sequence>
            <module name=”DependencyVendor_DependencyModule” />
            <module name=”DependencyVendor_DependencyModule” />
        </sequence>
    </module>
</config>

The above example has 2 dependencies. Your module may have more or none at all. Additional module nodes can be added to the sequence node in the case of more, or the sequence node can be removed entirely if there are no dependencies.

The version number for the module is indicated by setup_version in the main module node. Appropriately managing the version number is crucial when updating the module, as Magento will store and reference the version number during the setup:upgrade process to follow.

Step 3 – Enabling the module

Enabling the module will require access to your magento project’s command line interface. Once logged in, navigate to the magento root folder (named magento in our preceding examples), and then run this command:

php bin/magento module:enable VendorName_ModuleName

The CLI should provide some indication of whether the module was successfully enabled or not.

Once the module is enabled, the CLI will recommend some additional commands to run. It is advisable at this point to run the following commands to get Magento up to speed with your new module, whether it has a new version number, dependency injection changes, or database updates.

php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Further Steps

At this point in the process you now have an enabled Magento 2 module capable of delivering your business feature to your website! This is just the beginning, however. From here your module can be made to stall database tables and populate them with data, manipulate customer and product data, deliver a user interface to the storefront, and many other possibilities.

Have you ever tried to create your own Magento module? Do you have any questions about what to do next? Are you interested in our Magento 2 development services? Please comment below and we’ll be happy to discuss your thoughts.