✨ New MessageCollector utility class

This _internal-use only_ `PHP_CodeSniffer\Util\MessageCollector` class can be used to collect various type of "error" messages, including notices, warnings and deprecations for display at a later point in time.

This class is intended to be used by various steps in the PHPCS process flow to improve the error handling and prevent the "one error hiding another" pattern.

Design choices:
* This class does not have a constructor and has no awareness of the applicable `Config` or other aspects of a PHPCS run.
    If notices should be displayed conditionally, like only when not in `-q` quite mode, this should be handled by the class _using_ the `MessageCollector`.
* While duplicate error messages are not a great user experience, this class allows for them.
    It is the responsibility of the class _using_ the `MessageCollector` to ensure that the messages cached are informative for the end-user.
* The class provides a number of (`public`) class constants to indicate the error level when adding messages.
    It is _strongly_ recommended to only ever use these class constants for the error levels.
    The default error level for messages will be `NOTICE`.
    Note: yes, these class constants should basically be an Enum, however, enums are a PHP 8.1+ feature, so can't be used at this time.
* The class provides two (`public`) "orderby" class constants to indicate the display order of the messages.
    It is _strongly_ recommended to only ever use these class constants for the display order.
    By default, messages will be ordered by severity (with "order received" being the secondary ordering for messages of the same severity).
    Note: again, yes, these class constants should basically be an Enum.
* When display of the messages is requested and the message cache includes messages with severity `ERROR`, the class will throw a RuntimeException, which will cause the PHPCS run to exit with a non-zero exit code (currently `3`).
* In all other cases, the messages will be displayed, but the PHPCS run will continue without affecting the exit code.
* It was suggested by fredden to consider implementing [PSR-3: Logger Interface](https://www.php-fig.org/psr/psr-3/) for the `MessageCollector`.
    While we discussed this, I don't consider this necessary at this time, though as the class has no BC-promise, this can be reconsidered in the future.
    Arguments against implementing PSR-3 at this time:
    - Placeholder handling is required in the PSR-3 implementation to allow for logging to different contexts and using appropriate variable escaping based on the context.
        For PHPCS, messages will only ever be displayed on the command-line, so there is no need to take escaping for different contexts into account.
    - PSR-3 expects handling of eight different severity levels - emergency, alert, critical, error, warning, notice, info, debug -.
        For PHPCS, the `emergency`, `alert` and `critical` levels, as defined in PSR-3, are redundant as these will never occur.
        Along the same line, PHPCS does not log `info`.
        However, we do want to be able to display deprecation notices, but that is a severity level not supported under PSR-3.

The new functionality is fully covered by tests.

Potential future scope:
* Add a constructor and inject the `Config` class to allow for colorizing the messages/message prefixes if color support is enabled.
    This would be most effective after issue 448 has been addressed first.
* Add a new `CRITICAL` level for errors which prohibit the current task from finishing. When an error with such level would be received, it would cause the class to display all messages collected up to that point straight away via an exception.
* If the conditional displaying of the messages, like only when not in `-q` mode, would lead to undue duplicate code, potentially move display conditions handling into the `MessageCollector` class.
    This would also need the aforementioned constructor with `Config` injection.

Author: jrfnl

src/Util/MessageCollector.php

@@ -0,0 +1,310 @@
+<?php
+/**
+ * Collect messages for display at a later point in the process flow.
+ *
+ * If any message with type "error" is passed in, displaying the errors will result in halting the program
+ * with a non-zero exit code.
+ * If only messages with a lower severity are passed in, displaying the errors will be non-blocking
+ * and will not affect the exit code.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * This class is intended for internal use only and is not part of the public API.
+ * This also means that it has no promise of backward compatibility. Use at your own risk.
+ * ---------------------------------------------------------------------------------------------
+ *
+ * @internal
+ *
+ * @author    Juliette Reinders Folmer <[email protected]>
+ * @copyright 2025 PHPCSStandards and contributors
+ * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Util;
+
+use InvalidArgumentException;
+use PHP_CodeSniffer\Exceptions\RuntimeException;
+
+final class MessageCollector
+{
+
+    /**
+     * Indicator for a (blocking) error.
+     *
+     * @var int
+     */
+    const ERROR = 1;
+
+    /**
+     * Indicator for a warning.
+     *
+     * @var int
+     */
+    const WARNING = 2;
+
+    /**
+     * Indicator for a notice.
+     *
+     * @var int
+     */
+    const NOTICE = 4;
+
+    /**
+     * Indicator for a deprecation notice.
+     *
+     * @var int
+     */
+    const DEPRECATED = 8;
+
+    /**
+     * Indicator for ordering the messages based on severity first, order received second.
+     *
+     * @var string
+     */
+    const ORDERBY_SEVERITY = 'severity';
+
+    /**
+     * Indicator for ordering the messages based on the order in which they were received.
+     *
+     * @var string
+     */
+    const ORDERBY_RECEIVED = 'received';
+
+    /**
+     * Collected messages.
+     *
+     * @var array<array<string, string|int>> The value for each array entry is an associative array
+     *                                       which holds two keys:
+     *                                       - 'message' string The message text.
+     *                                       - 'type'    int    The type of the message based on the
+     *                                                          above declared error level constants.
+     */
+    private $cache = [];
+
+
+    /**
+     * Add a new message.
+     *
+     * @param string $message The message text.
+     * @param int    $type    The type of message. Should be one of the following constants:
+     *                        MessageCollector::ERROR, MessageCollector::WARNING, MessageCollector::NOTICE
+     *                        or MessageCollector::DEPRECATED.
+     *                        Defaults to MessageCollector::NOTICE.
+     *
+     * @return void
+     *
+     * @throws \InvalidArgumentException If the message text is not a string.
+     * @throws \InvalidArgumentException If the message type is not one of the accepted types.
+     */
+    public function add($message, $type=self::NOTICE)
+    {
+        if (is_string($message) === false) {
+            throw new InvalidArgumentException('The $message should be of type string. Received: '.gettype($message).'.');
+        }
+
+        if ($type !== self::ERROR
+            && $type !== self::WARNING
+            && $type !== self::NOTICE
+            && $type !== self::DEPRECATED
+        ) {
+            throw new InvalidArgumentException('The message $type should be one of the predefined MessageCollector constants. Received: '.$type.'.');
+        }
+
+        $this->cache[] = [
+            'message' => $message,
+            'type'    => $type,
+        ];
+
+    }//end add()
+
+
+    /**
+     * Determine whether or not the currently cached errors include blocking errors.
+     *
+     * @return bool
+     */
+    public function containsBlockingErrors()
+    {
+        $seenTypes     = $this->arrayColumn($this->cache, 'type');
+        $typeFrequency = array_count_values($seenTypes);
+        return isset($typeFrequency[self::ERROR]);
+
+    }//end containsBlockingErrors()
+
+
+    /**
+     * Display the cached messages.
+     *
+     * Displaying the messages will also clear the message cache.
+     *
+     * @param string $order Optional. The order in which to display the messages.
+     *                      Should be one of the following constants: MessageCollector::ORDERBY_SEVERITY,
+     *                      MessageCollector::ORDERBY_RECEIVED.
+     *                      Defaults to MessageCollector::ORDERBY_SEVERITY.
+     *
+     * @return void
+     *
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException When there are blocking errors.
+     */
+    public function display($order=self::ORDERBY_SEVERITY)
+    {
+        if ($this->cache === []) {
+            return;
+        }
+
+        $blocking    = $this->containsBlockingErrors();
+        $messageInfo = $this->prefixAll($this->cache);
+        $this->clearCache();
+
+        if ($order === self::ORDERBY_RECEIVED) {
+            $messages = $this->arrayColumn($messageInfo, 'message');
+        } else {
+            $messages = $this->sortBySeverity($messageInfo);
+        }
+
+        $allMessages = implode(PHP_EOL, $messages).PHP_EOL.PHP_EOL;
+
+        if ($blocking === true) {
+            throw new RuntimeException($allMessages);
+        } else {
+            echo $allMessages;
+        }
+
+    }//end display()
+
+
+    /**
+     * Label all messages based on their type.
+     *
+     * @param array<array<string, string|int>> $messages A multi-dimensional array of messages with their severity.
+     *
+     * @return array<array<string, string|int>>
+     */
+    private function prefixAll($messages)
+    {
+        foreach ($messages as $i => $details) {
+            $messages[$i]['message'] = $this->prefix($details['message'], $details['type']);
+        }
+
+        return $messages;
+
+    }//end prefixAll()
+
+
+    /**
+     * Add a message type prefix to a message.
+     *
+     * @param string $message The message text.
+     * @param int    $type    The type of message.
+     *
+     * @return string
+     */
+    private function prefix($message, $type)
+    {
+        switch ($type) {
+        case self::ERROR:
+            $message = 'ERROR: '.$message;
+            break;
+
+        case self::WARNING:
+            $message = 'WARNING: '.$message;
+            break;
+
+        case self::DEPRECATED:
+            $message = 'DEPRECATED: '.$message;
+            break;
+
+        default:
+            $message = 'NOTICE: '.$message;
+            break;
+        }
+
+        return $message;
+
+    }//end prefix()
+
+
+    /**
+     * Sort an array of messages by severity.
+     *
+     * @param array<array<string, string|int>> $messages A multi-dimensional array of messages with their severity.
+     *
+     * @return array<string> A single dimensional array of only messages, sorted by severity.
+     */
+    private function sortBySeverity($messages)
+    {
+        if (count($messages) === 1) {
+            return [$messages[0]['message']];
+        }
+
+        $errors       = [];
+        $warnings     = [];
+        $notices      = [];
+        $deprecations = [];
+
+        foreach ($messages as $details) {
+            switch ($details['type']) {
+            case self::ERROR:
+                $errors[] = $details['message'];
+                break;
+
+            case self::WARNING:
+                $warnings[] = $details['message'];
+                break;
+
+            case self::DEPRECATED:
+                $deprecations[] = $details['message'];
+                break;
+
+            default:
+                $notices[] = $details['message'];
+                break;
+            }
+        }
+
+        return array_merge($errors, $warnings, $notices, $deprecations);
+
+    }//end sortBySeverity()
+
+
+    /**
+     * Clear the message cache.
+     *
+     * @return void
+     */
+    private function clearCache()
+    {
+        $this->cache = [];
+
+    }//end clearCache()
+
+
+    /**
+     * Return the values from a single column in the input array.
+     *
+     * Polyfill for the PHP 5.5+ native array_column() function (for the functionality needed here).
+     *
+     * @param array<array<string, string|int>> $input     A multi-dimensional array from which to pull a column of values.
+     * @param string                           $columnKey The name of the column of values to return.
+     *
+     * @link https://www.php.net/function.array-column
+     *
+     * @return array<string|int>
+     */
+    private function arrayColumn(array $input, $columnKey)
+    {
+        if (function_exists('array_column') === true) {
+            // PHP 5.5+.
+            return array_column($input, $columnKey);
+        }
+
+        // PHP 5.4.
+        $callback = function ($row) use ($columnKey) {
+            return $row[$columnKey];
+        };
+
+        return array_map($callback, $input);
+
+    }//end arrayColumn()
+
+
+}//end class