Magento 2 registration.php

The registration.php file is the entry point for Magento's component discovery system. It registers modules, themes, and language packages with the ComponentRegistrar.

Purpose:

1. Tells Magento where to find the component
2. Registers the component type (module, theme, language)
3. Enables Magento to load the component's code
4. Provides the component's filesystem path

Module registration:

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

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

Theme registration:

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

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/Vendor/custom_theme',
    __DIR__
);

Language package registration:

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

ComponentRegistrar::register(
    ComponentRegistrar::LANGUAGE,
    'Vendor_Module_fr_FR',
    __DIR__
);

How Magento uses registration.php:

1. Magento scans app/code/ and vendor/ for registration.php files
2. Each file is included during bootstrapping
3. ComponentRegistrar::register() stores the component path
4. Magento reads app/etc/config.php to know which are enabled
5. Only enabled components are loaded into the application

The ComponentRegistrar is a registry that stores component paths and types.

ComponentRegistrar class:

<?php
namespace Magento\Framework\Component;

class ComponentRegistrar
{
    const MODULE = 'module';
    const THEME = 'theme';
    const LANGUAGE = 'language';
    
    private static $components = [];
    
    public static function register($componentType, $componentName, $path)
    {
        if (!isset(self::$components[$componentType])) {
            self::$components[$componentType] = [];
        }
        self::$components[$componentType][$componentName] = $path;
    }
    
    public static function getComponent($componentType)
    {
        return self::$components[$componentType] ?? [];
    }
    
    public static function getModuleList()
    {
        return self::getComponent(self::MODULE);
    }
}

Discovery process:

// Magento scans for registration.php files
$componentRegistrar = $objectManager->get(ComponentRegistrar::class);

// After all registration.php files are included:
$modules = ComponentRegistrar::getModuleList();
// Returns: [
//     'Magento_Catalog' => '/path/to/vendor/magento/module-catalog',
//     'Vendor_Module' => '/path/to/app/code/Vendor/Module',
//     ...
// ]

Registration file locations:

• Module: app/code/{Vendor}/{Module}/registration.php
• Theme: app/design/frontend/{Vendor}/{Theme}/registration.php
• Language: app/i18n/{Vendor}/{locale}/registration.php
• Composer package: vendor/{vendor}/{package}/registration.php

Autoloading registration.php:
Composer includes registration.php files automatically via the files autoload directive:

{
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

Follow these best practices when creating registration.php files.

Standard module registration:

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

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

Naming conventions:

• Module name: Vendor_Module (underscore-separated)
• Vendor name: PascalCase (e.g., MyCompany)
• Module name: PascalCase (e.g., ProductFilter)

Verification:

# Check if module is registered
php bin/magento module:status Vendor_Module

# List all registered modules
php bin/magento module:status

Common mistakes:

1. Wrong path: Ensure __DIR__ points to module root
2. Missing ComponentRegistrar import: Add use statement
3. Incorrect component type: Use ComponentRegistrar::MODULE
4. Naming mismatch: Name must match module.xml name

Debugging registration issues:

# Check if registration.php is loaded
grep -r "ComponentRegistrar::register" app/code/Vendor/Module/

# Verify module is in config.php
php bin/magento module:status

# Clear config cache
php bin/magento cache:clean config

Module name must match:

// registration.php
ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Vendor_Module',  // Must match module.xml
    __DIR__
);

<!-- module.xml -->
<module name="Vendor_Module" ...>
    <!-- Name must match registration.php -->
</module>

Themes and language packages use the same ComponentRegistrar system with different component types.

Theme registration:

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

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/Vendor/custom_theme',
    __DIR__
);

Theme naming format:

• Frontend: frontend/{Vendor}/{theme}
• Admin: adminhtml/{Vendor}/{theme}

Language package registration:

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

ComponentRegistrar::register(
    ComponentRegistrar::LANGUAGE,
    'Vendor_Module_fr_FR',
    __DIR__
);

Language naming format:

• {Vendor}_{Module}_{locale}
• Example: Magento_FR_fr or Vendor_Module_de_DE

Listing registered themes:

use Magento\Framework\Component\ComponentRegistrar;

$themes = ComponentRegistrar::getComponent(ComponentRegistrar::THEME);
foreach ($themes as $themePath => $dir) {
    echo $themePath . ' => ' . $dir . "\n";
}

Listing registered languages:

$languages = ComponentRegistrar::getComponent(ComponentRegistrar::LANGUAGE);
foreach ($languages as $langCode => $dir) {
    echo $langCode . ' => ' . $dir . "\n";
}

Verification commands:

# List all themes
php bin/magento theme:list

# List all languages
php bin/magento language:list

# Check theme status
php bin/magento theme:status