Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 42 ยท Modules

Your First Module

Build your first Magento 2 module: folder naming, registration.php, etc/module.xml, enabling it with setup:upgrade and checking it with module:status.

Every piece of custom Magento code lives in a module, so creating one is the first skill to learn. The good news is that a working module needs only two small files. Everything else (controllers, plugins, templates, database tables) is optional and added as you need it.

In this lesson you will create a module called Acme_Hello, see what each file does, and learn the commands that make Magento notice it. Because real Magento cannot run on this site, the real files are shown read-only, and the runnable examples are stand-ins: a module registry that reads module.xml-style definitions and a model of the enabled/disabled list.

Naming: Vendor_Module

Magento identifies a module by two parts joined by an underscore, Vendor_Module. Magento_Catalog is the core catalog module, and Acme_Hello is ours. The vendor part is your company or project name and the module part names the feature. Both use PascalCase, and both are used in three places that must agree:

Place Value for our module
Folder app/code/Acme/Hello
PHP namespace Acme\Hello
Module name in XML and CLI Acme_Hello

Magento's autoloader finds your classes through the namespace, so a class Acme\Hello\Model\Greeter must sit in app/code/Acme/Hello/Model/Greeter.php. A mismatch is the cause of many "class does not exist" errors.

The two required files

TEXT
app/code/Acme/Hello/
  registration.php
  etc/
    module.xml

registration.php tells Magento that this folder is a module and where it is:

PHP
<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Acme_Hello',
    __DIR__
);

When Magento starts it loads all registration.php files (modules installed with Composer are found through Composer's autoload settings) and collects the registered names and paths into a registry. This file only announces the module; it does not enable it.

etc/module.xml declares the module to the configuration system:

XML
<?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="Acme_Hello"/>
</config>

The name attribute must equal the name used in registration.php. You can add a <sequence> here to control load order, which is the topic of Module Sequence and Dependencies. Older modules also carried a setup_version attribute, which belonged to the install-script system. Modern modules use declarative schema and patches instead, so you normally leave it out in new code.

flowchart LR
    A["registration.php<br/>(announces name and path)"] --> B["Module registry"]
    B --> C["module.xml<br/>(declares the module)"]
    C --> D["config.php<br/>(enabled: 1 or 0)"]
    D --> E["Module is loaded<br/>on each request"]

A module must be registered, declared and enabled before Magento loads it.

Enabling the module

Registration and declaration are not enough. Magento keeps the list of enabled modules in app/etc/config.php. In a fresh project the file contains an entry for every module with 1 (enabled) or 0 (disabled), and a newly added module shows up there once Magento has detected it:

PHP
return [
    'modules' => [
        'Magento_Catalog' => 1,
        'Magento_Checkout' => 1,
        'Acme_Hello' => 1,
    ],
];

You do not edit this by hand. The command line does it:

Terminal
bin/magento module:status            # lists enabled and disabled modules
bin/magento module:enable Acme_Hello # adds it to config.php as enabled
bin/magento setup:upgrade            # applies database changes, updates module state
bin/magento cache:flush

setup:upgrade is the command you will run most. It detects new modules, runs schema and data patches, and refreshes the state Magento keeps in the database. After setup:upgrade, module:status should list Acme_Hello under the enabled modules. If it does not, the usual causes are:

  • the folder path or namespace does not match the module name,
  • registration.php is missing or has a typo in the name,
  • module.xml has invalid XML (Magento validates it against a schema),
  • the code was added but the cache is stale.

To turn a module off you run bin/magento module:disable Acme_Hello. Disabling stops it from loading but keeps its files and its database tables.

In developer mode, if a change to XML does not show up, run bin/magento cache:flush. Magento caches merged configuration, so stale XML is the most common reason a new file seems to be ignored.

A stand-in module registry

The following example builds a miniature registry. It parses module.xml-style strings with SimpleXML, checks that the declared name matches the registered name (the same mistake that breaks real modules), and prints a module:status style report. Magento's real registry and XML validation are much more thorough; the point here is the flow.

PHP Registering and reading module.xml

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Real Magento reports malformed or mismatched module declarations as errors during setup:upgrade or bootstrapping, and exact messages vary by version.

The second stand-in models app/etc/config.php. It shows what module:enable, module:disable and module:status do conceptually.

PHP A module:status simulation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The output layout imitates the real command's two lists, but the real one also reads state from configuration and tells you when a module cannot be disabled because another enabled module depends on it, which is the subject of the next lesson.

What comes next

With an enabled module you can add behaviour. The next folders you will meet are Controller/ for pages, Model/ for business logic, Block/ and view/ for output, and more XML in etc/. Each addition follows the same pattern: put a file in the right place, flush the cache, and Magento discovers it. Module Sequence and Dependencies comes next.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two files are required for a minimal Magento module?

    registration.php announces the module and its path, and etc/module.xml declares it. Everything else is optional.
  2. 2. For the module Acme_Hello, which PHP namespace and folder are correct?

    The vendor and module parts become both folder levels and namespace levels, and the module name joins them with an underscore.
  3. 3. A new module is registered and has a valid module.xml, but module:status does not list it. What is a typical fix?

    setup:upgrade detects new modules and updates their state. Also confirm that the folder, namespace and module name agree.
  4. 4. What does bin/magento module:disable Acme_Hello do?

    Disabling only changes the enabled flag. The code and data remain, so you can enable the module again later.

Summary

  • A module is named Vendor_Module; folder, namespace and name must agree.
  • registration.php announces the module and etc/module.xml declares it.
  • app/etc/config.php stores the enabled flag; use module:enable, module:disable and module:status.
  • bin/magento setup:upgrade discovers new modules and runs patches; flush the cache after XML changes.
  • Our registry and status examples are stand-ins for Magento's real, stricter implementation.

Next: Module Sequence and Dependencies