MAGETWO-64602: Sync config file with DB: Validation

Author: Bohdan Korablov

app/code/Magento/Deploy/Console/Command/App/ConfigImport/Importer.php

@@ -20,7 +20,7 @@
 class Importer
 {
     /**
-     * The manager of deployment configuration hash.
+     * The configuration data validator.
      *
      * @var Validator
      */

app/code/Magento/Deploy/Console/Command/App/ConfigImportCommand.php

@@ -13,10 +13,11 @@
 use Magento\Deploy\Console\Command\App\ConfigImport\Importer;
 
 /**
- * Imports data from deployment configuration files to the DB.
+ * Runs the process of importing configuration data from shared source to appropriate application sources.
  *
  * We have configuration files that are shared between environments, but some of the configurations are read only
- * from DB (e.g., themes, scopes and etc). This command is used to import such configurations from the file to DB.
+ * from DB (e.g., themes, scopes and etc). This command is used to import such configurations from the file to
+ * appropriate application sources.
  */
 class ConfigImportCommand extends Command
 {

app/code/Magento/Deploy/Model/DeploymentConfig/DataCollector.php

@@ -9,6 +9,20 @@
 
 /**
  * Config data collector of specific sections which are defined in di.xml
+ *
+ * E.g.
+ * ```xml
+ * <type name="Magento\Deploy\Model\DeploymentConfig\ImporterPool">
+ *     <arguments>
+ *          <argument name="importers" xsi:type="array">
+ *               <item name="scopes" xsi:type="string">Magento\Store\Model\StoreImporter</item>
+ *          </argument>
+ *     </arguments>
+ * </type>
+ * ```
+ * In here we define section "scopes" and its importer Magento\Store\Model\StoreImporter.
+ * The data of this section will be collected then will be used in importing process from the shared configuration
+ * files to appropriate application sources.
  */
 class DataCollector
 {
@@ -39,6 +53,17 @@ public function __construct(ImporterPool $configImporterPool, DeploymentConfig $
     /**
      * Retrieves configuration data of specific section from deployment configuration files.
      *
+     * E.g.
+     * ```php
+     *  [
+     *      'scopes' => [...],
+     *      'system' => [...],
+     *      'themes' => [...],
+     *      ...
+     *  ]
+     * ```
+     * In this example key of the array is the section name, value of the array is configuration data of the section.
+     *
      * @return array
      */
     public function getConfig()

app/code/Magento/Deploy/Model/DeploymentConfig/Hash.php

@@ -13,6 +13,8 @@
 
 /**
  * Saves and Retrieves deployment configuration hash.
+ *
+ * We need the hash of configuration data for its validation.
  */
 class Hash
 {
@@ -70,8 +72,10 @@ public function __construct(
     /**
      * Updates hash in the storage.
      *
+     * The hash is updated based on configuration data from shared configuration files.
+     *
      * @return void
-     * @throws LocalizedException
+     * @throws LocalizedException is thrown when import has failed
      */
     public function regenerate()
     {

app/code/Magento/Deploy/Model/DeploymentConfig/ImporterPool.php

@@ -12,6 +12,8 @@
 
 /**
  * Pool of all deployment configuration importers.
+ *
+ * All importers should implement Magento\Framework\App\DeploymentConfig\ImporterInterface interface.
  */
 class ImporterPool
 {
@@ -70,7 +72,8 @@ public function __construct(ObjectManagerInterface $objectManager, array $import
     }
 
     /**
-     * Retrieves sections from deployment configuration files which need to import into the DB.
+     * Retrieves sections from deployment configuration files which need to import into
+     * appropriate application sources.
      *
      * @return array the list of sections
      * E.g.

app/code/Magento/Deploy/Model/DeploymentConfig/Validator.php

@@ -9,6 +9,9 @@
 
 /**
  * Configuration data validator of specific sections in the deployment configuration files.
+ *
+ * This validator checks that configuration data from specific sections was not changed.
+ * If the data was changed validator returns false.
  */
 class Validator
 {
@@ -49,9 +52,12 @@ public function __construct(
     }
 
     /**
-     * Check if config data in the deployment configuration files is valid.
+     * Checks if config data in the deployment configuration files is valid.
      *
-     * If config data is empty always returns true because it means that nothing to import.
+     * Checks if config data was changed based on its hash.
+     * If the new hash of config data and the saved hash are different returns false.
+     * If config data is empty always returns true.
+     * In the other cases returns true.
      *
      * @return bool
      */

app/code/Magento/Deploy/Model/Plugin/ConfigValidator.php

@@ -9,11 +9,13 @@
 use Magento\Framework\App\FrontController;
 use Magento\Framework\App\RequestInterface;
 use Magento\Framework\Exception\LocalizedException;
-use Magento\Framework\Phrase;
 
 /**
+ * This is plugin for Magento\Framework\App\FrontController class.
+ *
  * Checks that config data form deployment configuration files was not changed.
- * If config data was changed throws LocalizedException.
+ * If config data was changed throws LocalizedException because we should stop work of Magento and then import
+ * config data from shared configuration files into appropriate application sources.
  */
 class ConfigValidator
 {
@@ -45,7 +47,7 @@ public function beforeDispatch(FrontController $subject, RequestInterface $reque
     {
         if (!$this->configValidator->isValid()) {
             throw new LocalizedException(
-                new Phrase(
+                __(
                     'A change in configuration has been detected.'
                     . ' Run app:config:import or setup:upgrade command to synchronize configuration.'
                 )