How to build a custom Magento 2 module

In the context of Magento, modules are small programs that you can build that extends functionality within your Magento project. They can become very complex but share several characteristics in their construction. Here I will show you how to build a basic ‘Hello World!’ module with Magento.

Magento is based primarily on PHP in an MVC (Model-View-Controller) architectural pattern. Despite this Magento tends to do things in a Magento specific way and the similarities between Magento and other PHP MVC frameworks such as Symfony and Laravel are not very apparent on first glance.

The Magento architecture is structured into layers and each layer is responsible for particular aspects of the system. Those layers are:

  • Domain Layer
  • Persistance Layer
  • Presentation Layer
  • Service Layer

A Magento module can affect one or more of these layers. A module, like a plugin in WordPress or a module in Drupal, adds extra functionality to the Magento system.

In this tutorial we will create a basic Hello World module with Magento.

Step 1. Create a new folder within the app/code directory of your Magento install named ‘Sample’

This is where you will group your custom extensions together. ‘Sample’ will be the vendor name.

Step 2. Create a new folder within your newly created directory named ‘HelloWorld’ to store your module code

This folder will be where your custom extension code resides.

Step 3. Create your registration.php file within this directory with the following code


The registrations.php file tells the Magento core system the name of the module and registers it in config.php when you run the command to activate it for the first time.

Step 4. Create a directory within your module code named ‘Controller’

This is where we will store the directory that houses our custom template for this particular module.

Step 5. Create a directory within your ‘Controller’ directory named ‘Index’

This is where the template will actually be stored.

Step 6. Within this ‘Index’ directory create a file named ‘Test.php’ with the following code

class Test extends \Magento\Framework\App\Action\Action
    protected $_pageFactory;

    public function __construct(
        \Magento\Framework\App\Action\Context $context,
        \Magento\Framework\View\Result\PageFactory $pageFactory)
        $this->_pageFactory = $pageFactory;
        return parent::__construct($context);

    public function execute()
        echo "Hello World";

This is the template that will be served to users when accessing a particular route on your Magento site.

Step 7. Create a directory named ‘etc’ within the ‘HelloWorld’ root directory

This is where routes, depency injection information and other specifications are stored in .xml files.

Step 8. Within the ‘etc’ directory create a file named ‘module.xml’ with the following code

<config xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">    <module name="Sample_HelloWorld" setup_version="1.0.0">

Step 9. Within the ‘etc’ directory create another directory named ‘frontend’

This is where you will store the routes.xml file.

Step 10. Within this directory create a file named ‘routes.xml’ with the following code

<?xml version="1.0" ?>
<config xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="standard">
        <route frontName="helloworld" id="helloworld">
            <module name="Sample_HelloWorld"/>

Step 11. In command line, goto the route of your application and run the following command

php bin/magento module:enable Sample_HelloWorld && php bin/magento setup:upgrade

This command will enable the module then update the setup configuration. This second step is necessary to complete the enabling process as it resets the config.

Step 12. Goto the following URL

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.