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 fileDescriptionStageConfiguration object
address_formats.xmlAddress format declarationprimary, global\Magento\Customer\Model\Address\Config
acl.xmlAccess Control Listglobal\Magento\Framework\Acl\AclResource\Provider
analytics.xml[Advanced reporting]https://developer.adobe.com/commerce/php/development/advanced-reporting/data-collection/)primary, global\Magento\Analytics\Model\Config\Reader
cache.xmlCache type declarationprimary, global\Magento\Framework\Cache\Config\Data
catalog_attributes.xmlCatalog attributes configurationglobal\Magento\Catalog\Model\Attribute\Config\Data
config.php and env.phpDeployment configurationThese files are readable/writeable by the internal config processor.Has no object, cannot be customized
config.xmlSystem configurationprimary, global\Magento\Framework\App\Config
communication.xmlDefines aspects of the message queue systemglobal\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Communication
crontab.xmlConfigures cron groupsglobal\Magento\Cron\Model\Config\Data
cron_groups.xmlSpecifies cron group optionsglobal\Magento\Cron\Model\Groups\Config\Data
db_schema.xmlDeclarative schemaglobalMagento\Framework\Setup\Declaration\Schema
di.xmlDependency injection configurationprimary, global, area\Magento\Framework\ObjectManager\Config
eav_attributes.xmlProvides EAV attributes configurationglobal\Magento\Eav\Model\Entity\Attribute\Config
email_templates.xmlEmail templates configurationglobal\Magento\Email\Model\Template\Config\Data
esconfig.xmlSearch engine locale stopwords configglobal\Magento\Elasticsearch\Model\Adapter\Index\Config\EsConfig
events.xmlEvent/observer configurationglobal, area\Magento\Framework\Event
export.xmlExport entity configurationglobal\Magento\ImportExport\Model\Export\Config
extension_attributes.xmlExtension attributesglobal\Magento\Framework\Api\ExtensionAttribute\Config
fieldset.xmlDefines fieldsetsglobal\Magento\Framework\DataObject\Copy\Config\Reader
indexer.xmlDeclares indexersglobal\Magento\Framework\Indexer\Config\Reader
import.xmlDeclares import entitiesglobal\Magento\ImportExport\Model\Import\Config
menu.xmlDefines menu items for the Adminadminhtml\Magento\Backend\Model\Menu\Config\Reader
module.xmlDefines module config data and soft dependencyprimary, global\Magento\Framework\Module\ModuleList\Loader
mview.xmlMView configurationprimary, global\Magento\Framework\Mview\Config\Data
payment.xmlPayment module configurationprimary, global\Magento\Payment\Model\Config
persistent.xmlMagento_Persistent configuration fileglobal\Magento\Persistent\Helper\Data
pdf.xmlPDF settingsglobal\Magento\Sales\Model\Order\Pdf\Config\Reader
product_options.xmlProvides product options configurationglobal\Magento\Catalog\Model\ProductOptions\Config
product_types.xmlDefines product typeglobal\Magento\Catalog\Model\ProductTypes\Config
queue_consumer.xmlDefines the relationship between an existing queue and its consumerglobal\Magento\Framework\MessageQueue\Consumer\Config\Xml\Reader
queue_publisher.xmlDefines the exchange where a topic is published.global\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher
queue_topology.xmlDefines the message routing rules, declares queues and exchangesglobal\Magento\Framework\MessageQueue\Topology\Config\Xml\Reader
reports.xmlAdvanced reportsglobal\Magento\Analytics\ReportXml\Config
resources.xmlDefines module resourceglobal\Magento\Framework\App\ResourceConnection\Config\Reader
routes.xmlRoute configurationareaMagento\Framework\App\Route\Config
sales.xmlDefines sales total configurationglobal\Magento\Sales\Model\Config\Data
search_engine.xmlProvides search engine configurationglobalMagento\Search\Model\SearchEngine\Config
search_request.xmlDefines catalog search configurationglobal\Magento\Framework\Search\Request\Config
sections.xmlDefines actions that trigger cache invalidation for private content blocksfrontendSectionInvalidationConfigReader
system.xmlDefines options for system configuration pageadminhtml\Magento\Framework\App\Config
validation.xmlModule validation configuration fileglobal\Magento\Framework\Validator\Factory
view.xmlDefines Vendor_Module view config valuesglobal\Magento\Framework\View\Config
webapi.xmlConfigures a web APIglobal\Magento\Webapi\Model\Config
webapi_async.xmlDefines REST custom routesglobal\Magento\WebapiAsync\Model\ServiceConfig
widget.xmlDefines widgetsglobal\Magento\Widget\Model\Config\Reader
zip_codes.xmlDefines zip code format for each countryglobal\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.

Previous pageConfiguration types
Next pageModule output

Commerce