|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +group: config-guide |
| 4 | +subgroup: Magento configuration files |
| 5 | +title: Create or extend configuration types |
| 6 | +menu_title: Create or extend configuration types |
| 7 | +menu_order: 10 |
| 8 | +github_link: config-guide/config/config-create.md |
| 9 | +--- |
| 10 | + |
| 11 | + |
| 12 | +#### Contents |
| 13 | + |
| 14 | +* <a href="#config-files-extend-create">Extend configuration types</a> |
| 15 | +* <a href="#config-files-extend-create-create">Create configuration types</a> |
| 16 | +* <a href="#config-files-validate">Validate a configuration type</a> |
| 17 | + |
| 18 | +<h2 id="config-files-extend-create">Extend configuration types</h2> |
| 19 | +To extend an existing configuration type, you need only create a configuration file in your module. |
| 20 | + |
| 21 | +For example, to add an event observer, you create `app/etc/events.xml` and declare a new observer. |
| 22 | + |
| 23 | +Because the event configuration type already exists in Magento, the loader and the `events.xsd` validating schema are already present and functional. |
| 24 | + |
| 25 | +Your new `events.xml` is automatically collected from your module and merged with other `events.xml` files for other modules. |
| 26 | + |
| 27 | +<h2 id="config-files-extend-create-create">Create configuration types</h2> |
| 28 | +To create new configuration type, you must add at minimum: |
| 29 | + |
| 30 | +* XML configuration files |
| 31 | +* XSD validation schema |
| 32 | +* A loader |
| 33 | + |
| 34 | +For example, to introduce an adapter for a new search server that enables extensions to configure how its entities are indexed in that server, create: |
| 35 | + |
| 36 | +* A loader. |
| 37 | +* An XSD schema. |
| 38 | +* Any other classes required for your new type to work. |
| 39 | +* An appropriately named configuration file. For example, `search.xml`. This file is read and validated against your schema. |
| 40 | + |
| 41 | + If other modules have a `search.xml` file, they are merged with your file when it loads. |
| 42 | + |
| 43 | +To create a new configuration type, extend the `\Magento\Framework\Config\ReaderInterface`, which is <a href="{{ site.mage2000url }}lib/internal/Magento/Framework/Config/Reader/Filesystem.php" target="_blank">Magento\Framework\Config\Reader\Filesystem</a> to provide the following parameters: |
| 44 | + |
| 45 | +* `$fileResolver`. Implements `\Magento\Framework\Config\FileResolverInterface`. This parameter lists the files containing the configurations of your custom type. |
| 46 | +* `$converter`. Implements `\Magento\Framework\Config\ConverterInterface`. This parameter converts the XML into the internal array representation of the configurations. |
| 47 | +* `$schemaLocator`. Implements `\Magento\Framework\Config/SchemaLocatorInterface`. This parameter provides the full path to file(s) containing schema(s) for validation of the individual and merged configuration files.</p> |
| 48 | +* `$validationState`. Implements `\Magento\Framework\Config\ValidationStateInterface`. This parameter defines whether a configuration file should be validated. |
| 49 | +* `$fileName`. Name of a configuration file. The Reader looks for the file names specified by this parameter in modules' `etc` directories. |
| 50 | +* `$idAttributes`. Array of note attribute IDs. |
| 51 | + |
| 52 | + For example, to merge the XML files: |
| 53 | + |
| 54 | + array( |
| 55 | + '</path/to/node>' => '<identifierAttributeName>', |
| 56 | + '</path/to/other/node>' => '<identifierAttributeName>', |
| 57 | + } |
| 58 | + |
| 59 | +* `$defaultScope`. Defines the configuration scope to be read by default. The default value for this parameter is global scope. |
| 60 | + |
| 61 | + After you customize `ReaderInterface`, you can use it to collect, merge, validate, and convert the configuration files to an internal array representation. |
| 62 | + |
| 63 | +<h2 id="config-files-validate">Validate a configuration type</h2> |
| 64 | + |
| 65 | +Each configuration file is validated against a schema specific to its configuration type. Example: events, which, in earlier Magento versions, were configured in `config.xml`, are now configured in `events.xml`. |
| 66 | + |
| 67 | +Configuration files can be validated both before (optional) and after any merge of multiple files affecting the same configuration type. Unless the validation rules for the individual and merged files are identical, you should provide two schemas for validating the configuration files: |
| 68 | + |
| 69 | +* Schema to validate an individual |
| 70 | +* Schema to validate a merged file |
| 71 | + |
| 72 | +New configuration files must be accompanied by XSD validation schemas. An XML configuration file and its XSD validation file must have the same name. |
| 73 | + |
| 74 | +If you must use two XSD files for a single XML file, the names of the schemas should be recognizable and associated with the XML file. |
| 75 | + |
| 76 | +If you have an `events.xml` file and a first `events.xsd` file, the XSD files for the merged `events.xml` file could be named `events_merged.xsd`. |
| 77 | + |
| 78 | +To ensure validation of an XML file by appropriate XSD file, you must specify the relative path to the XSD file in the XML file. For example: |
| 79 | + |
| 80 | + <config |
| 81 | + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| 82 | + xsi:noNamespaceSchemaLocation="../../../../../lib/internal/Magento/Framework/ObjectManager/etc/config.xsd"> |
| 83 | + |
| 84 | +Your IDE can validate your configuration files at both runtime during development. |
| 85 | + |
| 86 | +#### Related topics |
| 87 | + |
| 88 | +* <a href="{{ site.gdeurl }}config-guide/config/config-php.html">Module configuration files</a> |
| 89 | +* <a href="{{ site.gdeurl }}config-guide/config/config-php.html">Magento's deployment configuration, config.php</a> |
0 commit comments