Runner: show actionable information when PHPCS runs out of memory

As discussed in 3621, this PR adds a new function to show a "friendly" error message if/when PHPCS runs out of memory.

This functionality can't be tested via the unit/integration test suite as the PHP shutdown can't be mocked.

To test the functionality, I used a test run of PHPCS over its own code base with the following command:
```bash
phpcs -d memory_limit 32M
```

Fixes 3621

Co-authored-by: Alain Schlesser <[email protected]>

Author: jrfnl

src/Runner.php

@@ -53,6 +53,8 @@ class Runner
      */
     public function runPHPCS()
     {
+        $this->register_out_of_memory_shutdown_message('phpcs');
+
         try {
             Util\Timing::startTiming();
             Runner::checkRequirements();
@@ -153,6 +155,8 @@ public function runPHPCS()
      */
     public function runPHPCBF()
     {
+        $this->register_out_of_memory_shutdown_message('phpcbf');
+
         if (defined('PHP_CODESNIFFER_CBF') === false) {
             define('PHP_CODESNIFFER_CBF', true);
         }
@@ -886,4 +890,42 @@ public function printProgress(File $file, $numFiles, $numProcessed)
     }//end printProgress()
 
 
+    /**
+     * Registers a PHP shutdown function to provide a more informative out of memory error.
+     *
+     * @param string $command The command which was used to initiate the PHPCS run.
+     *
+     * @return void
+     */
+    private function register_out_of_memory_shutdown_message($command)
+    {
+        // Allocate all needed memory beforehand as much as possible.
+        $errorMsg    = PHP_EOL.'The PHP_CodeSniffer "%1$s" command ran out of memory.'.PHP_EOL;
+        $errorMsg   .= 'Either raise the "memory_limit" of PHP in the php.ini file or raise the memory limit at runtime'.PHP_EOL;
+        $errorMsg   .= 'using `%1$s -d memory_limit=512M` (replace 512M with the desired memory limit).'.PHP_EOL;
+        $errorMsg    = sprintf($errorMsg, $command);
+        $memoryError = 'Allowed memory size of';
+        $errorArray  = [
+            'type'    => 42,
+            'message' => 'Some random dummy string to take up memory and take up some more memory and some more',
+            'file'    => 'Another random string, which would be a filename this time. Should be relatively long to allow for deeply nested files',
+            'line'    => 31427,
+        ];
+
+        register_shutdown_function(
+            static function () use (
+                $errorMsg,
+                $memoryError,
+                $errorArray
+            ) {
+                $errorArray = error_get_last();
+                if (is_array($errorArray) === true && strpos($errorArray['message'], $memoryError) !== false) {
+                    echo $errorMsg;
+                }
+            }
+        );
+
+    }//end register_out_of_memory_shutdown_message()
+
+
 }//end class