Ruleset: wire in MessageCollector

This commit adds a mechanism to handle errors encountered while loading a ruleset in a more user-friendly manner.

* Errors and notices aimed at end-users and ruleset maintainers will be collected while processing the ruleset.
* Only once the complete processing of the ruleset is finished, will all errors/notices be displayed.
    This prevents "one error hiding behind another".
* If there are only notices (deprecations/notices/warnings), these will not display when running `-e` (explain), `-q` (quiet mode) or `--generator=...` (documentation).
* Errors will always display and will hard exit out of the run with a non-zero exit code.

This implementation should be seen as an interim - "good enough for now" - solution, which can be iterated on in the future.
I can imagine a more code-base wide solution at some later point in time, but that should not block this initial improvement.
As the current implementation doesn't change the public API (the only new methods are `private`), it should be feasible to transform the current solution to whatever form a future solution will take without breaking changes.

Includes tests covering the new functionality.

Author: jrfnl

src/Ruleset.php

@@ -14,6 +14,7 @@
 use PHP_CodeSniffer\Exceptions\RuntimeException;
 use PHP_CodeSniffer\Sniffs\DeprecatedSniff;
 use PHP_CodeSniffer\Util\Common;
+use PHP_CodeSniffer\Util\MessageCollector;
 use PHP_CodeSniffer\Util\Standards;
 use RecursiveDirectoryIterator;
 use RecursiveIteratorIterator;
@@ -138,21 +139,36 @@ class Ruleset
      */
     private $deprecatedSniffs = [];
 
+    /**
+     * Message collector object.
+     *
+     * User-facing messages should be collected via this object for display once the ruleset processing has finished.
+     *
+     * The following type of errors should *NOT* be collected, but should still throw their own `RuntimeException`:
+     * - Errors which could cause other (uncollectable) errors further into the ruleset processing, like a missing autoload file.
+     * - Errors which are directly aimed at and only intended for sniff developers or integrators
+     *   (in contrast to ruleset maintainers or end-users).
+     *
+     * @var \PHP_CodeSniffer\Util\MessageCollector
+     */
+    private $msgCache;
+
 
     /**
      * Initialise the ruleset that the run will use.
      *
      * @param \PHP_CodeSniffer\Config $config The config data for the run.
      *
      * @return void
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If no sniffs were registered.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If blocking errors were encountered when processing the ruleset.
      */
     public function __construct(Config $config)
     {
-        $this->config = $config;
-        $restrictions = $config->sniffs;
-        $exclusions   = $config->exclude;
-        $sniffs       = [];
+        $this->config   = $config;
+        $restrictions   = $config->sniffs;
+        $exclusions     = $config->exclude;
+        $sniffs         = [];
+        $this->msgCache = new MessageCollector();
 
         $standardPaths = [];
         foreach ($config->standards as $standard) {
@@ -249,6 +265,8 @@ public function __construct(Config $config)
             throw new RuntimeException('ERROR: No sniffs were registered');
         }
 
+        $this->displayCachedMessages();
+
     }//end __construct()
 
 
@@ -480,6 +498,35 @@ public function showSniffDeprecations()
     }//end showSniffDeprecations()
 
 
+    /**
+     * Print any notices encountered while processing the ruleset(s).
+     *
+     * Note: these messages aren't shown at the time they are encountered to avoid "one error hiding behind another".
+     * This way the (end-)user gets to see all of them in one go.
+     *
+     * @return void
+     *
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If blocking errors were encountered.
+     */
+    private function displayCachedMessages()
+    {
+        // Don't show deprecations/notices/warnings in quiet mode, in explain mode
+        // or when the documentation is being shown.
+        // Documentation and explain will call the Ruleset multiple times which
+        // would lead to duplicate display of the messages.
+        if ($this->msgCache->containsBlockingErrors() === false
+            && ($this->config->quiet === true
+            || $this->config->explain === true
+            || $this->config->generator !== null)
+        ) {
+            return;
+        }
+
+        $this->msgCache->display();
+
+    }//end displayCachedMessages()
+
+
     /**
      * Processes a single ruleset and returns a list of the sniffs it represents.
      *