Magento 2: Creating a Module

Magento 2 Logo

In this post we will look at the steps for adding your own custom Magento 2 module.

A module in it’s simplest form is a directory structure made up of various files including PHP, XML and PHTML to mention just a few of the types you might be working with. When building more advanced custom modules it is advisable to use examples from the core modules that make up Magento 2. Depending on how you installed the application core Magento 2 modules could be located in two different places. If you have cloned the GitHub repository they will be under app/code/Magento or more common is installation via composer where the modules will be located in the vender/magento/magento-* folders.

In this example we will be using the app/code folder to deploy our module. This is typical if the extension is project specific and is not going to be distributed or reused in other projects. For distribution or reuse a composer based module would be more appropriate. However, composer based module creation is out of scope for this post.

The directory structure of a module in Magento is made up of both the vendor name and the module name, e.g. Vendor/Module.

Create module directories

Lets go ahead and create the base directory structure for our module under the app/code directory.
Create the directories Examples/FirstModule

mkdir app/code/Examples

mkdir app/code/Examples/FirstModule

You should now have the following structure app/code/Examples/FirstModule.
Examples is our vendor name and FirstModule is our module name.

Registering the module

Two files are required as a minimum to register a Magento module, module.xml and registration.php

1. Create the module.xml file

First create the etc directory within our new module
mkdir app/code/Examples/FirstModule/etc

Next we will create a new file within the etc directory module.xml which contains the module name, version and dependencies.
Place the following code into the module.xml file.

<?xml version="1.0"?>
<config xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Examples_FirstModule" setup_version="0.0.1">

2. Create the registration.php file

The registration file tells Magento where the module is located and must be included. It follows the same pattern for all modules, just update the Vendor_ModuleName as required.

Create the file in app/code/Examples/FirstModule/registration.php and add the following code within.


use Magento\Framework\Component\ComponentRegistrar;


You should now have a directory structure and files like the following:


Notify Magento

Next we need to tell Magento about the new module.
From the root Magento directory using the CLI run the following command:

bin/magento setup:upgrade

Check module is active

Check the file app/etc/config.php within the file should be the line 'Examples_FirstModule' => 1,

grep Examples_FirstModule app/etc/config.php

What’s next?

Given the above module doesn’t really do anything yet and is simply registered with Magento ready to do something interesting, you could look at one of the following topics and add some functionality to your new module:

This series of posts assumes you are working with Magento 2 in developer mode, for more information on the differences between default / developer / production, please see this article.

Leave a Reply

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