Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 42 ยท Modules

Module Sequence and Dependencies

Control Magento 2 module load order with the sequence node in module.xml, declare package dependencies in composer.json, and see how config is merged in order.

Magento loads modules one after another, and the order matters. If your module changes something that the catalog module defines, your changes should be applied after the catalog module's own, otherwise they may be overwritten or may refer to something that does not exist yet. Two different files describe dependencies, and beginners often confuse them: module.xml controls load order inside Magento, and composer.json controls which packages are installed.

In this lesson you will learn what each file is responsible for, how Magento computes the final load order, and how configuration from many modules is merged using that order. The real files are read-only, and two runnable stand-ins show the ordering algorithm and the merge.

The sequence node in module.xml

To say "load me after the catalog module", you list it in the sequence section of etc/module.xml:

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_Badges">
        <sequence>
            <module name="Magento_Catalog"/>
            <module name="Magento_Customer"/>
        </sequence>
    </module>
</config>

This says Acme_Badges must come after Magento_Catalog and Magento_Customer. Magento reads every enabled module's sequence list and sorts the modules so that each one follows all the modules it names. The resulting order is written to the modules list in app/etc/config.php when the list is updated, for example by setup:upgrade.

Sequence does three practical things:

  • Files that are merged across modules (di.xml, events.xml, layout files and others) are combined in load order, so later modules can extend or override earlier ones.
  • If a module in the sequence is disabled or missing, Magento reports it instead of silently loading things in a wrong state.
  • You cannot disable a module while enabled modules depend on it unless you force it.

Two rules deserve attention. First, only list modules you really depend on, because every entry is a hard constraint. Second, circular sequences are an error: if A follows B and B follows A, no order exists. Magento detects this during module loading and stops with an error, and you must remove one of the references.

Sequence only controls load order among Magento modules. It does not download anything. Declaring Magento_Catalog in the sequence does not install it, and a missing module will be reported as a problem.

The module's composer.json

Modules shipped as packages carry a composer.json at the module root. It tells Composer what the module is, which other packages it needs, and how to autoload it:

JSON
{
  "name": "acme/module-badges",
  "description": "Adds product badges to the catalog",
  "type": "magento2-module",
  "version": "1.0.0",
  "license": "proprietary",
  "require": {
    "php": "~8.2.0||~8.3.0",
    "magento/framework": "^103.0",
    "magento/module-catalog": "^104.0"
  },
  "autoload": {
    "files": ["registration.php"],
    "psr-4": {
      "Acme\\Badges\\": ""
    }
  }
}

Important parts:

  • "type": "magento2-module" marks it for the Magento installer plugin.
  • require lists package dependencies and version ranges. The numbers shown here are placeholders: the framework and module packages have their own version numbers that differ from the 2.4.x release number, so look them up in the versions you actually use.
  • autoload.files runs registration.php on every request, which is how Composer-installed modules register themselves.
  • autoload.psr-4 maps the Acme\Badges namespace to the module root so classes are found without extra configuration.

When your module is a loose folder in app/code, a composer.json is optional. When you distribute it, it is mandatory. Keep both files in agreement: if composer.json requires magento/module-catalog, the module.xml sequence should usually mention Magento_Catalog as well. The first guarantees the code is installed, and the second guarantees the load order.

flowchart TD
    C["composer.json<br/>require: installs packages"] --> I["Package is installed"]
    X["module.xml sequence<br/>after: Magento_Catalog"] --> O["Load order is computed"]
    I --> O
    O --> M["Config files merged in order"]

Composer decides what is installed, the sequence decides in which order installed modules load.

Computing the load order

Magento performs a topological sort: it repeatedly picks a module whose prerequisites are already placed. When several modules are free to go, a stable tie-breaker (such as alphabetical order or the original list order) gives the same result every time. The stand-in below implements this with cycle detection and a missing-module check.

PHP Sorting modules by sequence

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 real implementation lives in the framework's module list code and reports errors in its own wording. What matters is the idea: dependencies first, stable order, and loud failure for cycles and gaps.

Config merging across modules

Magento's configuration files have the same name in many modules. Every module may have an etc/di.xml, etc/events.xml or etc/config.xml. Magento collects the file from each enabled module in load order and merges them into one configuration. Roughly:

  • For XML files, elements are matched by an identifying attribute defined per file type (for example name or id). A later file can add new nodes or replace the content of a node with the same identifier.
  • For config.xml, default setting values from all modules end up in one tree, and later modules win when two set the same path.

This is the reason load order matters: if Acme_Badges and another module both set the same default, the one loaded later wins. The stand-in merges simple configuration arrays in load order and records which module won each value.

PHP Merging config in load order

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.

In practice you rarely fight over the same default. The point is to remember that an unexpected value is often a sequence issue, and that changing the order (through sequence) is the supported way to fix it. The next lesson explains how areas split these files further, in Areas and Configuration Files.

Common mistakes

  • Missing sequence. Your module's di.xml or layout change works on your machine but not on production, because the load order happened to differ.
  • Too many sequence entries. Listing modules you do not need makes your module harder to install and can create cycles.
  • Forgetting composer.json requirements. The sequence names a module that is not installed on a client's store.
  • Editing the order by hand in config.php. The file is rewritten by Magento commands. Fix the sequence instead.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the sequence node in module.xml control?

    Sequence lists modules that must load before this one. Installation is Composer's job.
  2. 2. Which file ensures a package dependency is actually downloaded when your module is installed from a package?

    The require section of composer.json lists packages that Composer must install. module.xml sequence only affects load order.
  3. 3. Module A is declared to come after B and B after A. What happens?

    No valid order exists, so loading fails with an error and you must remove one of the sequence entries.
  4. 4. Two modules set the same config.xml default path. Which value does the final configuration use?

    Files are merged in load order, so the later module's value overrides the earlier one.

Summary

  • sequence in module.xml sets load order; composer.json require sets what gets installed. Use both.
  • Magento sorts modules so each follows its prerequisites and fails on cycles and missing modules.
  • Configuration files with the same name are merged across modules in load order; later modules win conflicts.
  • Keep sequence lists minimal and never edit order by hand in config.php.

Next: Areas and Configuration Files