Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 42 ยท Modules

Areas and Configuration Files

Understand Magento 2 areas (global, frontend, adminhtml, webapi_rest, graphql, crontab), how etc/ and etc/frontend/ files differ, and how XML is merged per area.

Magento serves very different kinds of requests: a shopper browsing the storefront, an administrator editing products, a mobile app calling the REST API, a cron job running in the background. Each of these needs different behaviour, and loading everything for all of them would be slow and risky. A customer-facing page should not load the admin menu, and an admin action should not trigger storefront-only observers.

Magento solves this with areas. An area is a named context that decides which configuration files, layouts, templates and observers are active for the current request. In this lesson you will learn the main areas, where a module puts files for each one, how files are merged, and how an area-aware merge works in a runnable stand-in.

The areas

The names you will use most often:

Area code Used for
frontend The storefront customers see
adminhtml The admin panel
global (the files directly in etc/) Shared by all areas, the base configuration
webapi_rest REST API requests
webapi_soap SOAP API requests
graphql GraphQL requests
crontab Cron job execution

The base configuration is often called "global" in code and "base" in conversation. Its files sit directly in the module's etc/ folder. Anything in etc/frontend/ applies only to the frontend area, and so on. The area for a request is chosen early, from the URL or the entry point: storefront URLs get frontend, the admin URL path gets adminhtml, and /rest/... requests get webapi_rest. Your code can ask the framework for the current area through the app state class, and you can set an area code in a CLI script when you need it.

Some area names appear as both strings in XML paths and constants in PHP (the Area class). The folder names on disk are the same strings you see above: etc/frontend, etc/adminhtml, etc/webapi_rest, etc/graphql, etc/crontab.

Where module files go

A module's etc/ folder holds its configuration, split by scope. A typical module might look like this (not every module has all of them):

TEXT
Acme/Badges/etc/
  module.xml           global, always
  di.xml               global dependency injection
  events.xml           global events
  db_schema.xml        database tables (global)
  acl.xml              admin permissions (global)
  config.xml           default configuration values (global)
  frontend/
    di.xml             frontend-only DI changes
    events.xml         frontend-only observers
    routes.xml         storefront routes
  adminhtml/
    di.xml
    events.xml
    routes.xml         admin routes
    system.xml         admin configuration screens
    menu.xml           admin menu
  webapi_rest/
    di.xml
  crontab/
    di.xml

Which file may live where is defined by Magento, not by you. For example routes.xml is area-specific (a route belongs to the storefront or the admin), whereas module.xml, db_schema.xml and acl.xml are global. If you place a file in the wrong folder, it is usually ignored or rejected by the XML schema, so check the layout shown in the core modules when unsure. Versions and details can differ slightly, which is why the table above avoids promising more than the common cases.

You will see these files in later lessons: Preferences and Interfaces in di.xml, Events and Observers, Routing and Controllers and System Configuration.

How files are merged

For a request in a given area, Magento builds configuration like this:

  1. Collect the file (for example di.xml) from the global etc/ folder of every enabled module, in load order, and merge them.
  2. Collect the file from the area's folder (etc/frontend/di.xml) of every module, in load order, and merge it on top of the global result.

So area files extend or override global ones, but only for requests in that area. The same DI setup can therefore differ between the storefront and the admin without duplicating anything.

Merging happens at the XML node level, not as simple text concatenation. Each file type declares which attributes identify a node (for example, the for attribute of a <preference>, or the name of an observer). Nodes with the same identifier are merged, later ones overwrite earlier ones, and nodes with new identifiers are added. Magento validates the merged result with an XML schema, so a typo shows up as an error instead of silently doing nothing.

flowchart TD
    G1["Module A etc/di.xml"] --> GM["Merged global di.xml"]
    G2["Module B etc/di.xml"] --> GM
    GM --> FM["Frontend config =<br/>global + frontend overrides"]
    F1["Module A etc/frontend/di.xml"] --> FM
    F2["Module B etc/frontend/di.xml"] --> FM
    GM --> AM["Admin config =<br/>global + adminhtml overrides"]
    A1["Module A etc/adminhtml/di.xml"] --> AM

Area configuration is the merged global file with the merged area file layered on top.

A stand-in area-aware merger

The first example parses small XML strings with SimpleXML and merges <preference for="..." type="..."/> nodes identified by the for attribute. It first merges all global files in module order, then layers an area on top. This is a simplified version of what Magento does generically for many file types.

PHP Merging di.xml-style files per area

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 the output, the second global file replaced the logger preference of the first (later module wins), and the frontend file replaced the mailer only for the storefront. The admin area keeps the global mailer.

The second stand-in is a small area resolver: it decides the area from a request path (like Magento does from the URL) and lists which of a module's files would be loaded.

PHP Which files load for which area

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 URL prefixes here are made up for the demo. In a real store the admin path is configurable (it is not always /admin), and routes decide the area through the area-specific routes.xml, so never hard-code these assumptions in real modules.

Practical rules

  • Put configuration in the narrowest area that needs it. An observer for storefront behaviour belongs in etc/frontend/events.xml, not in the global file.
  • Use the global file for things that must work everywhere, such as a preference for a service used by the storefront, admin and API.
  • When a change "does not work", check the area first: the right file in the wrong folder is the most common reason.
  • Flush the cache after changing XML. Merged configuration is cached per area.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where would you put an observer that should run only for storefront requests?

    Area folders limit a file to one area. Storefront-only behaviour belongs in etc/frontend.
  2. 2. How is configuration for the frontend area built?

    Magento merges the global files in module load order, then layers the area files over the result.
  3. 3. Which area handles requests whose URL starts with /rest/ in a default setup?

    REST API requests are served in the webapi_rest area, which has its own etc/webapi_rest folder for overrides.
  4. 4. Two merged files contain a node with the same identifying attribute. What happens?

    Nodes are matched by their identifier and the later file overrides the earlier one, which is why load order matters.
  5. 5. Why is configuration split into areas at all?

    Areas keep storefront, admin, API and cron behaviour separate, which avoids unwanted side effects and unnecessary work.

Summary

  • An area is a request context: frontend, adminhtml, webapi_rest, webapi_soap, graphql, crontab, plus the shared global base.
  • Global files live in etc/; area files live in etc/<area>/.
  • Magento merges global files in module order, then layers the area's files on top; nodes are matched by identifying attributes.
  • Put configuration in the narrowest area, and flush the cache after XML changes.
  • The merger and area resolver here are stand-ins; the real versions validate against XML schemas.

Next: The Object Manager and Constructor Injection