#3361 New Configuration Type Topic

Author: Raul E Watson

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

@@ -21,42 +21,29 @@ Your new `events.xml` is automatically collected from your module and merged wit
 
 To create new configuration type, you must add at minimum:
 
-*  [XML](https://glossary.magento.com/xml) configuration files
-*  [XSD](https://glossary.magento.com/xsd) validation schema
 *  A loader
+*  [XSD](https://glossary.magento.com/xsd) validation schema
+*  [XML](https://glossary.magento.com/xml) configuration files
 
 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:
 
 *  A loader.
-*  An XSD schema.
-*  Any other classes required for your new type to work.
+*  An XSD schema file.
 *  An appropriately named configuration file. For example, `search.xml`. This file is read and validated against your schema.
+*  Any other classes required for your new type to work.
 
-   If other modules have a `search.xml` file, they are merged with your file when it loads.
-
-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:
-
-*  `$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.
-*  `$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.
-*  `$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.
-*  `$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.
-*  `$fileName`. Name of a configuration file. The Reader looks for the file names specified by this parameter in modules' `etc` directories.
-*  `$idAttributes`. Array of node attribute IDs.
-
-    For example, to merge the XML files:
-
-       array(
-         '</path/to/node>' => '<identifierAttributeName>',
-         '</path/to/other/node>' => '<identifierAttributeName>',
-       }
+{:.bs-callout-info}
+If new modules have a `search.xml` file, they will be merged with your file when it loads.
 
-*  `$defaultScope`. Defines the configuration scope to be read by default. The default value for this parameter is global scope.
+### Examples of use  
 
-After you customize `ReaderInterface`, you can use it to collect, merge, validate, and convert the configuration files to an internal array representation.
+To create a new configuration type:
 
-### Examples of use
+1. Create your XSD file
+2. Create your XML file
+3. Define your configuration object in your `di.xml` 
 
-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 to create a configuration object.
+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.
 
 ```xml
 <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
@@ -83,12 +70,35 @@ The following example from the Magento_Sales module's [di.xml]({{ site.mage2blob
     </type>
 </config>
 ```
+* The first type node sets the Reader's filename, associated `Converter` and `SchemaLocator` classes.
+* 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). 
+* 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.
+
+
+3. Define a reader by extending [Magento\Framework\Config\Reader\Filesystem]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/Reader/Filesystem.php) class to provide the following parameters:
+
+{:.bs-callout-info}
+You can also implement `ReaderInterface` to create your own version of the reader. For reference see [Magento_Analytics config reader]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Analytics/ReportXml/Config/Reader.php)
+
+```php
+namespace Vendor\ModuleName\Model\Config;
+
+class Reader extends \Magento\Framework\Config\Reader\Filesystem
+{
+    /**
+     * List of identifier attributes for merging
+     *
+     * @var array
+     */
+    protected $_idAttributes = [
+         '</path/to/node_in_your_xml_file>'          => '<identifierAttributeName>',
+         '</path/to/other/node_in_your_xml_file>'    => '<identifierAttributeName>',
+    ];
+}
+```
 
-The first type node sets the Reader's filename, associated `Converter` and `SchemaLocator` classes.
-
-Then, the `pdfConfigDataStorage` virtual type attaches that reader class to an instance of [Magento\Framework\Config\Data]({{ site.mage2bloburl }}/{{ page.guide_version }}/lib/internal/Magento/Framework/Config/Data.php). 
+After define your reader, you can use it to collect, merge, validate, and convert the configuration files to an internal array representation.
 
-And finally, the last type 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.
 
 ## Validate a configuration type {#config-files-validate}
 
@@ -115,4 +125,5 @@ Your IDE can validate your configuration files at both runtime and during develo
 Related topics
 
 *  [Module configuration files]({{ page.baseurl }}/config-guide/config/config-php.html)
+*  [Configuration file merge]({{ page.baseurl }}/guides/v2.3/config-guide/config/config-files.html#config-files-load-merge-merge)
 *  [Magento's deployment configuration]({{ page.baseurl }}/config-guide/config/config-php.html)

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

@@ -50,6 +50,9 @@ Magento's merge algorithm follows:
 
 After configuration files are merged, the resulting document contains all nodes from the original files.
 
+{:.bs-callout-info}
+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.
+
 ## Configuration types, objects, and interfaces {#config-files-classes}
 
 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
 
 ### Configuration interfaces {#config-files-classes-int}
 
-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.
+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]({{ page.baseurl }}/config-guide/config/config-create.html#config-files-extend-create-create).
 
 `Magento\Framework\Config` provides the following interfaces: