Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit f4b0900

Browse files
doboothdobooth
authored
Merge pull request #6539 from diazwatson/3361_newConfigurationType
#3361 New Configuration Type Topic
2 parents 722df7b + f12bf92 commit f4b0900

File tree

2 files changed

+77
-24
lines changed

2 files changed

+77
-24
lines changed

‎src/guides/v2.3/config-guide/config/config-create.md‎

Lines changed: 71 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -21,40 +21,89 @@ Your new `events.xml` is automatically collected from your module and merged wit
2121

2222
To create new configuration type, you must add at minimum:
2323

24-
* [XML](https://glossary.magento.com/xml) configuration files
25-
* XSD validation schema
2624
* A loader
25+
* [XSD](https://glossary.magento.com/xsd) validation schema
26+
* [XML](https://glossary.magento.com/xml) configuration files
2727

2828
For example, to introduce an [adapter](https://glossary.magento.com/adapter) for a new search server that enables extensions to configure how its entities are indexed in that server, create:
2929

30-
* A loader.
31-
* An XSD schema.
32-
* Any other classes required for your new type to work.
30+
* A loader
31+
* An XSD schema file
3332
* An appropriately named configuration file. For example, `search.xml`. This file is read and validated against your schema.
33+
* Any other classes required for your work.
34+
35+
{:.bs-callout-info}
36+
If new modules have a `search.xml` file, they will be merged with your file when it loads.
37+
38+
### Examples of use
39+
40+
To create a new configuration type:
3441

35-
If other modules have a `search.xml` file, they are merged with your file when it loads.
42+
1. Create your XSD file.
43+
1. Create your XML file.
44+
1. Define your configuration object in your `di.xml`.
3645

37-
To create a new configuration type, extend the `\Magento\Framework\Config\ReaderInterface`, which is [Magento\Framework\Config\Reader\Filesystem]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/Reader/Filesystem.php) to provide the following parameters:
46+
The following example from the Magento_Sales module's [di.xml]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Sales/etc/di.xml) illustrates how a configuration object should look like.
3847

39-
* `$fileResolver`. Implements [\Magento\Framework\Config\FileResolverInterface]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/FileResolverInterface.php). This parameter lists the files containing the configurations of your custom type.
40-
* `$converter`. Implements [\Magento\Framework\Config\ConverterInterface]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/ConverterInterface.php). This parameter converts the XML into the internal array representation of the configurations.
41-
* `$schemaLocator`. Implements [\Magento\Framework\Config\SchemaLocatorInterface]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/SchemaLocatorInterface.php). This parameter provides the full path to file(s) containing schema(s) for validation of the individual and merged configuration files.
42-
* `$validationState`. Implements [\Magento\Framework\Config\ValidationStateInterface]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/ValidationStateInterface.php). This parameter defines whether a configuration file should be validated.
43-
* `$fileName`. Name of a configuration file. The Reader looks for the file names specified by this parameter in modules' `etc` directories.
44-
* `$idAttributes`. Array of node attribute IDs.
48+
```xml
49+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
4550

46-
For example, to merge the XML files:
51+
<type name="Magento\Sales\Model\Order\Pdf\Config\Reader">
52+
<arguments>
53+
<argument name="fileName" xsi:type="string">pdf.xml</argument>
54+
<argument name="converter" xsi:type="object">Magento\Sales\Model\Order\Pdf\Config\Converter</argument>
55+
<argument name="schemaLocator" xsi:type="object">Magento\Sales\Model\Order\Pdf\Config\SchemaLocator</argument>
56+
</arguments>
57+
</type>
4758

48-
```php
49-
array(
50-
'</path/to/node>' => '<identifierAttributeName>',
51-
'</path/to/other/node>' => '<identifierAttributeName>',
52-
}
59+
<virtualType name="pdfConfigDataStorage" type="Magento\Framework\Config\Data">
60+
<arguments>
61+
<argument name="reader" xsi:type="object">Magento\Sales\Model\Order\Pdf\Config\Reader</argument>
62+
<argument name="cacheId" xsi:type="string">sales_pdf_config</argument>
63+
</arguments>
64+
</virtualType>
65+
66+
<type name="Magento\Sales\Model\Order\Pdf\Config">
67+
<arguments>
68+
<argument name="dataStorage" xsi:type="object">pdfConfigDataStorage</argument>
69+
</arguments>
70+
</type>
71+
</config>
5372
```
5473

55-
* `$defaultScope`. Defines the configuration scope to be read by default. The default value for this parameter is global scope.
74+
* The first type node sets the Reader's filename, associated `Converter` and `SchemaLocator` classes.
75+
* Then, the `pdfConfigDataStorage` virtual type node attaches the reader class to an instance of [Magento\Framework\Config\Data]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/Data.php).
76+
* And finally, the last type node attaches that config data virtual type to the [Magento\Sales\Model\Order\Pdf\Config]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Sales/Model/Order/Pdf/Config.php) class, which is used for actually reading values in from those [pdf.xml]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Sales/etc/pdf.xml) files.
77+
78+
1. Define a reader by extending [Magento\Framework\Config\Reader\Filesystem]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/Reader/Filesystem.php) class and rewrite the following parameters:
79+
80+
```php
81+
$_idAttributes // Array of node attribute IDs.
82+
```
83+
84+
**Example:**
85+
86+
```php
87+
namespace Vendor\ModuleName\Model\Config;
88+
89+
class Reader extends \Magento\Framework\Config\Reader\Filesystem
90+
{
91+
/**
92+
* List of identifier attributes for merging
93+
*
94+
* @var array
95+
*/
96+
protected $_idAttributes = [
97+
'</path/to/node_in_your_xml_file>' => '<identifierAttributeName>',
98+
'</path/to/other/node_in_your_xml_file>' => '<identifierAttributeName>',
99+
];
100+
}
101+
```
102+
103+
{:.bs-callout-info}
104+
If you prefer to create your own version of the reader you can do so by implementing `\Magento\Framework\Config\ReaderInterface`. For reference see [Magento_Analytics config reader]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Analytics/ReportXml/Config/Reader.php)
56105

57-
After you customize `ReaderInterface`, you can use it to collect, merge, validate, and convert the configuration files to an internal array representation.
106+
After defining your reader, use it to collect, merge, validate, and convert the configuration files to an internal array representation.
58107

59108
## Validate a configuration type {#config-files-validate}
60109

@@ -68,9 +117,7 @@ Configuration files can be validated both before (optional) and after any merge
68117
New configuration files must be accompanied by XSD validation schemas. An XML configuration file and its XSD validation file must have the same name.
69118

70119
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.
71-
72120
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`.
73-
74121
To ensure validation of an XML file by appropriate XSD file, you must add the Uniform Resource Name (URN) to the XSD file in the XML file. For example:
75122

76123
```xml
@@ -83,4 +130,5 @@ Your IDE can validate your configuration files at both runtime and during develo
83130
Related topics
84131

85132
* [Module configuration files]({{ page.baseurl }}/config-guide/config/config-php.html)
133+
* [Configuration file merge]({{ page.baseurl }}/config-guide/config/config-files.html#config-files-load-merge-merge)
86134
* [Magento's deployment configuration]({{ page.baseurl }}/config-guide/config/config-php.html)

‎src/guides/v2.3/config-guide/config/config-files.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,9 @@ Magento's merge algorithm follows:
5050

5151
After configuration files are merged, the resulting document contains all nodes from the original files.
5252

53+
{:.bs-callout-info}
54+
Note that you can use [\Magento\Framework\Config\Reader\Filesystem]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/Reader/Filesystem.php) class for debugging and understanding the logic behind [configuration files loader]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/Reader/Filesystem.php#L125) and [merge configs]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/Reader/Filesystem.php#L144) process.
55+
5356
## Configuration types, objects, and interfaces {#config-files-classes}
5457

5558
The following sections provide information about configuration types, their corresponding configuration objects, and interfaces you can use to work with the objects:
@@ -113,7 +116,9 @@ Configuration file|Description|Stage|Configuration object
113116

114117
### Configuration interfaces {#config-files-classes-int}
115118

116-
You can interact with configuration files using interfaces under [Magento\Framework\Config]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config). You can also use these interfaces if you create new configuration types.
119+
You can interact with configuration files using interfaces under [Magento\Framework\Config]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config).
120+
121+
You can also use these interfaces if you [create new configuration types]({{ page.baseurl }}/config-guide/config/config-create.html#config-files-extend-create-create).
117122

118123
`Magento\Framework\Config` provides the following interfaces:
119124

0 commit comments

Comments
 (0)