Step-by-Step Creating a Magento Module

Naming Convention

Magento modules follow the Vendor_ModuleName pattern:

• Vendor: Your company or unique namespace (e.g., Amazon, Webkul, MageWorx)
• ModuleName: Descriptive name in PascalCase (e.g., PrepManager, WarrantyPro, ShippingCalc)

Examples:

• Amazon_Prep
• Amazon_Shipping
• Amazon_Warranty

Directory Structure

app/code/Amazon/Prep/
├── registration.php                    (required)
├── etc/
│   └── module.xml                      (required)
├── Model/
│   └── PrepManager.php
├── Controller/
│   └── Index/
│       └── Index.php
├── Block/
│   └── PrepManager.php
├── view/
│   └── frontend/
│       ├── layout/
│       │   └── default.xml
│       ├── templates/
│       │   └── prep_manager.phtml
│       └── web/
│           ├── css/
│           └── js/
└── etc/
    ├── frontend/
    │   └── routes.xml
    └── di.xml

Minimal Module Requirements

A module needs only two files:

1. registration.php — registers the module with Magento
2. etc/module.xml — declares the module and its dependencies

Everything else is optional and added as needed.

Purpose

registration.php tells Magento's autoloader where to find your module's classes and registers the module in the system.

Complete File

<?php

use Magento\Framework\Component\ComponentRegistrar;

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

How It Works

1. ComponentRegistrar::register() adds your module to Magento's module registry
2. The first argument ComponentRegistrar::MODULE specifies this is a module registration
3. The second argument is your module's unique name (Vendor_Module)
4. The third argument __DIR__ points to the module's root directory

PSR-4 Autoloading

Magento automatically configures PSR-4 autoloading for registered modules:

Amazon\Prep\ → app/code/Amazon/Prep/

So class Amazon\Prep\Model\PrepManager maps to app/code/Amazon/Prep/Model/PrepManager.php.

Common Mistakes

// WRONG: Missing leading backslash on namespace
ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Amazon_Prep',
    __DIR__
);
// This is actually correct - no namespace prefix needed

// WRONG: Typo in module name
ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Amazon_Prep',  // Must match module.xml
    __DIR__
);

// WRONG: Using absolute path
ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Amazon_Prep',
    'C:\magento\app\code\Amazon\Prep'  // Use __DIR__ instead
);

Verification

After creating registration.php, verify:

bin/magento module:status
# Should show Amazon_Prep in the list (disabled)

Purpose

module.xml declares your module to Magento, specifying its name, version, and dependencies on other modules.

Complete File

<?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="Amazon_Prep" setup_version="1.0.0">
        <sequence>
            <module name="Magento_Catalog"/>
            <module name="Magento_Customer"/>
        </sequence>
    </module>
</config>

Module Attributes

Sequence Dependencies

The <sequence> tag lists modules your module depends on:

<sequence>
    <!-- These modules load BEFORE Amazon_Prep -->
    <module name="Magento_Catalog"/>
    <module name="Magento_Customer"/>
    <module name="Magento_Store"/>
</sequence>

Why use sequence:

• Your code uses classes from these modules
• You need their database tables to exist
• You extend their configuration
• You need their events/observers loaded first

Module Version

The setup_version is used for database schema upgrades:

<!-- First release -->
<module name="Amazon_Prep" setup_version="1.0.0">

<!-- After adding a database table -->
<module name="Amazon_Prep" setup_version="1.1.0">

<!-- After adding a column -->
<module name="Amazon_Prep" setup_version="1.2.0">

Check Required Dependencies

Find which modules you need to depend on:

# Check what classes you're using
grep -r "use Magento\\" app/code/Amazon/Prep/ | sort -u

# Each Magento\ namespace maps to a module:
# Magento\Catalog\ → Magento_Catalog
# Magento\Customer\ → Magento_Customer
# Magento\Store\ → Magento_Store

Step-by-Step Process

Step 1: Create Directory

mkdir -p app/code/Amazon/Prep/etc
mkdir -p app/code/Amazon/Prep/Model
mkdir -p app/code/Amazon/Prep/Controller/Index
mkdir -p app/code/Amazon/Prep/Block
mkdir -p app/code/Amazon/Prep/view/frontend/layout
mkdir -p app/code/Amazon/Prep/view/frontend/templates

Step 2: Create registration.php

<?php
use Magento\Framework\Component\ComponentRegistrar;

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

Step 3: Create module.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="Amazon_Prep" setup_version="1.0.0">
        <sequence>
            <module name="Magento_Catalog"/>
        </sequence>
    </module>
</config>

Step 4: Verify Module Exists

bin/magento module:status

Output should include:

List of enabled modules:
...

List of disabled modules:
Amazon_Prep

Step 5: Enable Module

bin/magento module:enable Amazon_Prep
bin/magento setup:upgrade
bin/magento cache:clean

Step 6: Verify in Admin

Go to Stores > Configuration — your module is now part of the system.

File Checklist

Common Errors

# Error: Module not found
bin/magento module:status | grep Amazon
# Fix: Check registration.php path and module name

# Error: Dependency not satisfied
bin/magento setup:upgrade fails
# Fix: Add missing modules to <sequence> in module.xml

# Error: Class not found
# Fix: Check namespace matches directory structure (PSR-4)