Overview of module configuration files

The responsibilities of the config.xml configuration file used in earlier versions of Commerce is now divided between several files, located in various module directories. Commerce’s multiple configuration files load on demand only when a module requests a specific configuration type.

You can use these files—also referred to as configuration types—to customize specific aspects of your module’s behavior.

Multiple modules can declare configuration files that affect the same configuration type (for example, events), and these multiple configuration files are merged.

Following are common terms used in this topic:

  • Configuration object—The Commerce library or class that is responsible for defining and validating the configuration type. For example, the configuration object for config.xml is Magento\Framework\App\Config.

  • Configuration stage—Stages are defined as primary, global, and area. Each stage determines when configuration type is loaded and merged with same-named configuration types. For example, module.xml files are merged with other module.xml files.

  • Configuration scope—Complementary to configuration stages, a scope defines the configuration type model. For example, adminhtml is an area scope that is loaded with at the stage with other modules’ adminhtml configurations. For more information, see Modules and areas.

Configuration load and merge

This section discusses how configuration files are loaded and merged.

How Commerce loads configuration files

Commerce loads configuration files in the following order (all paths are relative to your Commerce installation directory):

  • Primary configuration (app/etc/di.xml). This file is used to bootstrap Commerce.
  • Global configurations from modules (<your component base dir>/<vendorname>/<component-type>-<component-name>/etc/*.xml). Collects certain configuration files from all modules and merges them together.
  • Area-specific configuration from modules (<your component base dir>/<vendorname>/<component-type>-<component-name>/etc/<area>/*.xml). Collects configuration files from all modules and merges them into the global configuration. Some area-specific configurations can override or extend the global configuration.

where

  • <your component base dir> is the base directory in which your component is located. Typical values are app/code or vendor relative to the Commerce installation directory.

  • <vendorname> is the component’s vendor name; for example, Commerce’s vendor name is magento.

  • <component-type> is one of the following:

    • module-: An extension or module.
    • theme-: Theme.
    • language-: Language package.
INFO
Currently, themes are located under <magento_root>/app/design/frontend or <magento_root>/app/design/adminhtml.
  • <component-name>: Name of your component as defined in composer.json.

Configuration file merge

Nodes in configuration files are merged based on their fully qualified XPaths, which has a special attribute defined in $idAttributes array declared as its identifier. This identifier must be unique for all nodes nested under the same parent node.

Commerce application merge algorithm:

  • If node identifiers are equal (or if there is no identifier defined), all underlying content in the node (attributes, child nodes, and scalar content) is overridden.
  • If node identifiers are not equal, the node is a new child of the parent node.
  • If the original document has multiple nodes with the same identifier, an error is triggered because the identifiers cannot be distinguished.

After configuration files are merged, the resulting document contains all nodes from the original files.

INFO
You can use \Magento\Framework\Config\Reader\Filesystem class for debugging and understanding the logic behind configuration files loader and merge configs process.

Configuration types, objects, and interfaces

The following sections provide information about configuration types, their corresponding configuration objects, and interfaces that you can use to work with the objects:

Configuration types and objects

The following table shows each configuration type and the Commerce configuration object to which it relates.

Configuration file
Description
Stage
Configuration object
address_formats.xml
Address format declaration
primary, global
\Magento\Customer\Model\Address\Config
acl.xml
Access Control List
global
\Magento\Framework\Acl\AclResource\Provider
analytics.xml
Advanced reporting
primary, global
\Magento\Analytics\Model\Config\Reader
cache.xml
Cache type declaration
primary, global
\Magento\Framework\Cache\Config\Data
catalog_attributes.xml
Catalog attributes configuration
global
\Magento\Catalog\Model\Attribute\Config\Data
config.php and env.php
Deployment configuration
These files are readable/writeable by the internal config processor.
Has no object, cannot be customized
config.xml
System configuration
primary, global
\Magento\Framework\App\Config
communication.xml
Defines aspects of the message queue system
global
\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Communication
crontab.xml
Configures cron groups
global
\Magento\Cron\Model\Config\Data
cron_groups.xml
Specifies cron group options
global
\Magento\Cron\Model\Groups\Config\Data
db_schema.xml
Declarative schema
global
Magento\Framework\Setup\Declaration\Schema
di.xml
Dependency injection configuration
primary, global, area
\Magento\Framework\ObjectManager\Config
eav_attributes.xml
Provides EAV attributes configuration
global
\Magento\Eav\Model\Entity\Attribute\Config
email_templates.xml
Email templates configuration
global
\Magento\Email\Model\Template\Config\Data
esconfig.xml
Search engine locale stopwords config
global
\Magento\Elasticsearch\Model\Adapter\Index\Config\EsConfig
events.xml
Event/observer configuration
global, area
\Magento\Framework\Event
export.xml
Export entity configuration
global
\Magento\ImportExport\Model\Export\Config
extension_attributes.xml
Extension attributes
global
\Magento\Framework\Api\ExtensionAttribute\Config
fieldset.xml
Defines fieldsets
global
\Magento\Framework\DataObject\Copy\Config\Reader
indexer.xml
Declares indexers
global
\Magento\Framework\Indexer\Config\Reader
import.xml
Declares import entities
global
\Magento\ImportExport\Model\Import\Config
menu.xml
Defines menu items for the Admin
adminhtml
\Magento\Backend\Model\Menu\Config\Reader
module.xml
Defines module config data and soft dependency
primary, global
\Magento\Framework\Module\ModuleList\Loader
mview.xml
MView configuration
primary, global
\Magento\Framework\Mview\Config\Data
payment.xml
Payment module configuration
primary, global
\Magento\Payment\Model\Config
persistent.xml
Magento_Persistent configuration file
global
\Magento\Persistent\Helper\Data
pdf.xml
PDF settings
global
\Magento\Sales\Model\Order\Pdf\Config\Reader
product_options.xml
Provides product options configuration
global
\Magento\Catalog\Model\ProductOptions\Config
product_types.xml
Defines product type
global
\Magento\Catalog\Model\ProductTypes\Config
queue_consumer.xml
Defines the relationship between an existing queue and its consumer
global
\Magento\Framework\MessageQueue\Consumer\Config\Xml\Reader
queue_publisher.xml
Defines the exchange where a topic is published.
global
\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher
queue_topology.xml
Defines the message routing rules, declares queues and exchanges
global
\Magento\Framework\MessageQueue\Topology\Config\Xml\Reader
reports.xml
Advanced reports
global
\Magento\Analytics\ReportXml\Config
resources.xml
Defines module resource
global
\Magento\Framework\App\ResourceConnection\Config\Reader
routes.xml
Route configuration
area
Magento\Framework\App\Route\Config
sales.xml
Defines sales total configuration
global
\Magento\Sales\Model\Config\Data
search_engine.xml
Provides search engine configuration
global
Magento\Search\Model\SearchEngine\Config
search_request.xml
Defines catalog search configuration
global
\Magento\Framework\Search\Request\Config
sections.xml
Defines actions that trigger cache invalidation for private content blocks
frontend
SectionInvalidationConfigReader
system.xml
Defines options for system configuration page
adminhtml
\Magento\Framework\App\Config
validation.xml
Module validation configuration file
global
\Magento\Framework\Validator\Factory
view.xml
Defines Vendor_Module view config values
global
\Magento\Framework\View\Config
webapi.xml
Configures a web API
global
\Magento\Webapi\Model\Config
webapi_async.xml
Defines REST custom routes
global
\Magento\WebapiAsync\Model\ServiceConfig
widget.xml
Defines widgets
global
\Magento\Widget\Model\Config\Reader
zip_codes.xml
Defines zip code format for each country
global
\Magento\Directory\Model\Country\Postcode\Config\Data

Configuration interfaces

You can interact with configuration files using interfaces under Magento\Framework\Config.

You can use these interfaces if you create a configuration type.

Magento\Framework\Config provides the following interfaces:

That is, the file system, database, other storage merges the configuration files according to the merging rules, and validates the configuration files with the validation schemas.

386822bd-e32c-40a8-81c2-ed90ad1e198c