[3.x] Add "--xdebug" CLI option to enabled Xdebug

src/bin/phpmd

@@ -16,8 +16,8 @@
  * @link http://phpmd.org/
  */
 
-use Composer\XdebugHandler\XdebugHandler;
 use PHPMD\TextUI\Command;
+use PHPMD\TextUI\XdebugOptionHandler;
 
 if (file_exists(__DIR__ . '/../../../../autoload.php')) {
     // phpmd is part of a composer installation
@@ -26,24 +26,24 @@ if (file_exists(__DIR__ . '/../../../../autoload.php')) {
     require_once __DIR__ . '/../../vendor/autoload.php';
 }
 
+// Check PHP setup for CLI arguments
+if (!isset($_SERVER['argv']) && !isset($argv)) {
+    fwrite(STDERR, 'Please enable the "register_argc_argv" directive in your php.ini', PHP_EOL);
+    exit(1);
+} elseif (!isset($argv)) {
+    $argv = $_SERVER['argv'];
+}
+
 // Restart if xdebug is loading, unless the environment variable PHPMD_ALLOW_XDEBUG is set.
-$xdebug = new XdebugHandler('PHPMD');
-$xdebug->check();
-unset($xdebug);
+$xdebugHandler = new XdebugOptionHandler('PHPMD');
+$xdebugHandler->check();
+unset($xdebugHandler);
 
 if (!ini_get('date.timezone')) {
     date_default_timezone_set('UTC');
 }
 
 ini_set('memory_limit', -1);
 
-// Check php setup for cli arguments
-if (!isset($_SERVER['argv']) && !isset($argv)) {
-    fwrite(STDERR, 'Please enable the "register_argc_argv" directive in your php.ini', PHP_EOL);
-    exit(1);
-} elseif (!isset($argv)) {
-    $argv = $_SERVER['argv'];
-}
-
 // Run command line interface
 exit(Command::main($argv)->value);

src/main/php/PHPMD/TextUI/CommandLineOptions.php

@@ -893,6 +893,7 @@ public function usage()
             '--color: enable color in output' . \PHP_EOL .
             '--extra-line-in-excerpt: Specify how many extra lines are added ' .
             'to a code snippet in html format' . \PHP_EOL .
+            '--xdebug: Enable Xdebug for debugging' . \PHP_EOL .
             '--: Explicit argument separator: Anything after "--" will be read as an argument even if' .
             'it starts with "-" or matches the name of an option' . \PHP_EOL;
     }

src/main/php/PHPMD/TextUI/XdebugOptionHandler.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace PHPMD\TextUI;
+
+use Composer\XdebugHandler\XdebugHandler;
+
+/**
+ * Xdebug CLI Option Handler
+ *
+ * Enables instead of disables Xdebug, if called with "--xdebug" CLI option.
+ */
+class XdebugOptionHandler extends XdebugHandler
+{
+    /**
+     * Rebuilds the run command with Xdebug enabled, instead, if CLI option "--xdebug" is used
+     */
+    protected function restart(array $command): void
+    {
+        if (in_array('--xdebug', $command, true)) {
+            // Unset unwanted command arguments & options
+            if (($xdebugKey = array_search('--xdebug', $command, true)) !== false) {
+                unset($command[$xdebugKey]);
+            }
+            if (($noConfigKey = array_search('-n', $command, true)) !== false) {
+                unset($command[$noConfigKey]);
+            }
+            if (($configKey = array_search('-c', $command, true)) !== false) {
+                unset($command[$configKey + 1]);
+                unset($command[$configKey]);
+            }
+
+            // The PHP INI entries to enable Xdebug
+            $activateXdebugOptions[] = '-d xdebug.mode=debug';
+            $activateXdebugOptions[] = '-d xdebug.start_with_request=on';
+
+            // Inject the activating command options just after the PHP binary
+            array_splice($command, 1, 0, $activateXdebugOptions);
+
+            fwrite(STDERR, 'Restarting PHP Mess Detector with Xdebug enabled:' . PHP_EOL);
+            fwrite(STDERR, implode(' ', $command) . PHP_EOL);
+            fwrite(STDERR, PHP_EOL);
+        }
+
+        if ($command) {
+                parent::restart($command);
+        }
+    }
+}

src/site/rst/documentation/index.rst

@@ -96,6 +96,8 @@ Command line options
   - ``--color`` - enable color in output, for instance text renderer
     will show rule name in yellow and error description in red.
 
+  - ``--xdebug`` - will enable Xdebug for debugging PHP Mess Detector.
+
   An example command line: ::
 
     phpmd PHP/Depend/DbusUI xml codesize --reportfile phpmd.xml --suffixes php,phtml