#3361 New Configuration Type Topic

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

@@ -21,40 +21,89 @@ 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 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.
+*  A loader
+*  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 work.
+
+{:.bs-callout-info}
+If new modules have a `search.xml` file, they will be merged with your file when it loads.
+
+### Examples of use
+
+To create a new configuration type:
 
-   If other modules have a `search.xml` file, they are merged with your file when it loads.
+1. Create your XSD file.
+1. Create your XML file.
+1. Define your configuration object in your `di.xml`.
 
-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:
+    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.
 
-*  `$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.
+    ```xml
+    <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
 
-    For example, to merge the XML files:
+        <type name="Magento\Sales\Model\Order\Pdf\Config\Reader">
+            <arguments>
+                <argument name="fileName" xsi:type="string">pdf.xml</argument>
+                <argument name="converter" xsi:type="object">Magento\Sales\Model\Order\Pdf\Config\Converter</argument>
+                <argument name="schemaLocator" xsi:type="object">Magento\Sales\Model\Order\Pdf\Config\SchemaLocator</argument>
+            </arguments>
+        </type>
 
-    ```php
-      array(
-        '</path/to/node>' => '<identifierAttributeName>',
-        '</path/to/other/node>' => '<identifierAttributeName>',
-      }
+        <virtualType name="pdfConfigDataStorage" type="Magento\Framework\Config\Data">
+            <arguments>
+                <argument name="reader" xsi:type="object">Magento\Sales\Model\Order\Pdf\Config\Reader</argument>
+                <argument name="cacheId" xsi:type="string">sales_pdf_config</argument>
+            </arguments>
+        </virtualType>
+
+        <type name="Magento\Sales\Model\Order\Pdf\Config">
+            <arguments>
+                <argument name="dataStorage" xsi:type="object">pdfConfigDataStorage</argument>
+            </arguments>
+        </type>
+    </config>
     ```
 
-*  `$defaultScope`. Defines the configuration scope to be read by default. The default value for this parameter is global scope.
+   *  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.
+
+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:
+
+   ```php
+   $_idAttributes // Array of node attribute IDs.
+   ```
+
+**Example:**
+
+```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>',
+    ];
+}
+```
+
+{:.bs-callout-info}
+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)
 
- After you customize `ReaderInterface`, you can use it to collect, merge, validate, and convert the configuration files to an internal array representation.
+After defining your reader, use it to collect, merge, validate, and convert the configuration files to an internal array representation.
 
 ## Validate a configuration type {#config-files-validate}
 
@@ -68,9 +117,7 @@ Configuration files can be validated both before (optional) and after any merge
 New configuration files must be accompanied by XSD validation schemas. An XML configuration file and its XSD validation file must have the same name.
 
 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.
-
 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`.
-
 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:
 
 ```xml
@@ -83,4 +130,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 }}/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: