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.

On this page