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 othermodule.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 areapp/code
orvendor
relative to the Commerce installation directory. -
<vendorname>
is the component’s vendor name; for example, Commerce’s vendor name ismagento
. -
<component-type>
is one of the following:module-
: An extension or module.theme-
: Theme.language-
: Language package.
<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.
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.
address_formats.xml
catalog_attributes.xml
config.php
and env.php
communication.xml
eav_attributes.xml
esconfig.xml
extension_attributes.xml
module.xml
product_options.xml
queue_consumer.xml
queue_publisher.xml
queue_topology.xml
resources.xml
search_engine.xml
search_request.xml
sections.xml
zip_codes.xml
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:
- 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.