Module configuration files

Overview of module configuration files

The responsibilities of the config.xml configuration file used in earlier versions of Magento is now divided between several files, located in various module directories. Magento’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 Magento 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. For more information, see Configuration load and merge.
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 Magento loads configuration files

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

Primary configuration (app/etc/di.xml). This file is used to bootstrap Magento.
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 Magento installation directory.
<vendorname> is the component’s vendor name; for example, Magento’s vendor name is magento.
<component-type> is one of the following:
- module-: An extension or module.
- theme-: Theme.
- language-: Language package.

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.

Magento’s merge algorithm follows:

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.

Configuration types, objects, and interfaces

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

Configuration types and objects
Configuration interfaces

Configuration types and objects

The following table shows each configuration type and the Magento 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`	Elasticsearch 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 admin panel	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.xml`	Message queue configuration. Deprecated for [RabbitMQ] usage	global	\Magento\Framework\MessageQueue\Config\Reader\Xml
`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 also use these interfaces if you create new configuration types.

Magento\Framework\Config provides the following interfaces:

Framework\Config\ConverterInterface, which converts the XML into an in-memory array representation of the configurations.
Framework\Config\DataInterface, which retrieves the configuration data in a specified scope.
Framework\Config\FileResolverInterface, which identifies the location of files to be read by Magento\Framework\Config\ReaderInterface.
Framework\Config\ReaderInterface, which reads the configuration data from storage and selects the storage from which it reads.

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.

Framework\Config\SchemaLocatorInterface, which locates the XSD schema.
Framework\Config\ScopeListInterface, which returns a list of scopes.
Framework\Config\ValidationStateInterface, which retrieves the validation state.