Implement generation of XDebug filter script as described in #3272.

This adds the new CLI option --dump-xdebug-filter which will generate a PHP
script that can be used to set a whitelist filter for XDebug's code coverage
collector in order to speed up test runs.

The whitelist is based on the filter configuration in PHPUnit's XML
configuration. If the configuration only contains includes for files and
directories without prefixes and suffixes other than '.php', the XDebug script
will contain the same whitelist items.

If, however, the filter configuration is more complex, the XDebug script will
contain the resolved list of files, which will have a negative impact on
performance.

src/TextUI/Command.php

@@ -140,6 +140,7 @@ class Command
         'verbose'                   => null,
         'version'                   => null,
         'whitelist='                => null,
+        'dump-xdebug-filter='       => null,
     ];
 
     /**
@@ -740,6 +741,11 @@ protected function handleArguments(array $argv): void
 
                     break;
 
+                case '--dump-xdebug-filter':
+                    $this->arguments['xdebugFilterFile'] = $option[1];
+
+                    break;
+
                 default:
                     $optionName = \str_replace('--', '', $option[0]);
 
@@ -1081,6 +1087,7 @@ protected function showHelp(): void
   --whitelist <dir>           Whitelist <dir> for code coverage analysis
   --disable-coverage-ignore   Disable annotations for ignoring code coverage
   --no-coverage               Ignore code coverage configuration
+  --dump-xdebug-filter <file> Generate script to set Xdebug code coverage filter
 
 Logging Options:
 

src/TextUI/TestRunner.php

@@ -41,6 +41,7 @@
 use PHPUnit\Util\TestDox\HtmlResultPrinter;
 use PHPUnit\Util\TestDox\TextResultPrinter;
 use PHPUnit\Util\TestDox\XmlResultPrinter;
+use PHPUnit\Util\XDebugFilterScriptGenerator;
 use ReflectionClass;
 use SebastianBergmann\CodeCoverage\CodeCoverage;
 use SebastianBergmann\CodeCoverage\Exception as CodeCoverageException;
@@ -455,7 +456,7 @@ public function doRun(Test $suite, array $arguments = [], bool $exit = true): Te
             $codeCoverageReports = 0;
         }
 
-        if ($codeCoverageReports > 0) {
+        if ($codeCoverageReports > 0 || isset($arguments['xdebugFilterFile'])) {
             $codeCoverage = new CodeCoverage(
                 null,
                 $this->codeCoverageFilter
@@ -540,6 +541,17 @@ public function doRun(Test $suite, array $arguments = [], bool $exit = true): Te
                 }
             }
 
+            if (isset($arguments['xdebugFilterFile'], $filterConfiguration)) {
+                $filterScriptGenerator = new XDebugFilterScriptGenerator();
+                $script                = $filterScriptGenerator->generate(
+                    $filterConfiguration['whitelist'],
+                    $this->codeCoverageFilter->getWhitelist()
+                );
+                \file_put_contents($arguments['xdebugFilterFile'], $script);
+
+                exit(self::SUCCESS_EXIT);
+            }
+
             if (!$this->codeCoverageFilter->hasWhitelist()) {
                 if (!$whitelistFromConfigurationFile && !$whitelistFromOption) {
                     $this->writeMessage('Error', 'No whitelist is configured, no code coverage will be generated.');

src/Util/XDebugFilterScriptGenerator.php

@@ -0,0 +1,82 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Util;
+
+class XDebugFilterScriptGenerator
+{
+    public function generate(array $filterData, array $whitelistedFiles): string
+    {
+        $items = $this->getItems($filterData, $whitelistedFiles);
+
+        $files = \array_map(function ($item) {
+            return \sprintf("        '%s'", $item);
+        }, $items);
+        $files = \implode(",\n", $files);
+
+        return <<<EOF
+<?php
+if (!\\function_exists('xdebug_set_filter')) {
+    return;
+}
+
+xdebug_set_filter(
+    XDEBUG_FILTER_CODE_COVERAGE,
+    XDEBUG_PATH_WHITELIST,
+    [
+$files
+    ]
+);
+
+EOF;
+    }
+
+    private function getItems(array $filterData, array $whitelistedFiles): array
+    {
+        if ($this->canUseRawFilterData($filterData)) {
+            return $this->getItemsFromRawFilterData($filterData);
+        }
+
+        return $whitelistedFiles;
+    }
+
+    private function getItemsFromRawFilterData(array $filterData): array
+    {
+        $files = [];
+
+        if (isset($filterData['include']['directory'])) {
+            foreach ($filterData['include']['directory'] as $directory) {
+                $files[] = $directory['path'];
+            }
+        }
+
+        if (isset($filterData['include']['directory'])) {
+            foreach ($filterData['include']['file'] as $file) {
+                $files[] = $file;
+            }
+        }
+
+        return $files;
+    }
+
+    private function canUseRawFilterData(array $filterData): bool
+    {
+        if (\count($filterData['exclude']['directory']) > 0 || \count($filterData['exclude']['file'])) {
+            return false;
+        }
+
+        foreach ($filterData['include']['directory'] as $directory) {
+            if (($directory['suffix'] !== '' && $directory['suffix'] !== '.php') || $directory['prefix'] !== '') {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

tests/_files/configuration_whitelist.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8" ?>
+
+<phpunit>
+
+  <filter>
+    <whitelist>
+      <file>AbstractTest.php</file>
+    </whitelist>
+  </filter>
+
+</phpunit>
+

tests/end-to-end/dump-xdebug-filter.phpt

@@ -0,0 +1,30 @@
+--TEST--
+phpunit -c ../_files/configuration_whitelist.xml --dump-xdebug-filter 'php://stdout'
+--SKIPIF--
+<?php
+if (!extension_loaded('xdebug')) {
+    print 'skip: xdebug not loaded';
+}
+--FILE--
+<?php
+$_SERVER['argv'][1] = '-c';
+$_SERVER['argv'][2] = __DIR__ . '/../_files/configuration_whitelist.xml';
+$_SERVER['argv'][3] = '--dump-xdebug-filter';
+$_SERVER['argv'][4] = 'php://stdout';
+
+require __DIR__ . '/../bootstrap.php';
+PHPUnit\TextUI\Command::main();
+--EXPECTF--
+PHPUnit %s by Sebastian Bergmann and contributors.
+<?php
+if (!\function_exists('xdebug_set_filter')) {
+    return;
+}
+
+xdebug_set_filter(
+    XDEBUG_FILTER_CODE_COVERAGE,
+    XDEBUG_PATH_WHITELIST,
+    [
+        %s
+    ]
+);

tests/end-to-end/help.phpt

@@ -24,6 +24,7 @@ Code Coverage Options:
   --whitelist <dir>           Whitelist <dir> for code coverage analysis
   --disable-coverage-ignore   Disable annotations for ignoring code coverage
   --no-coverage               Ignore code coverage configuration
+  --dump-xdebug-filter <file> Generate script to set Xdebug code coverage filter
 
 Logging Options:
 

tests/end-to-end/help2.phpt

@@ -25,6 +25,7 @@ Code Coverage Options:
   --whitelist <dir>           Whitelist <dir> for code coverage analysis
   --disable-coverage-ignore   Disable annotations for ignoring code coverage
   --no-coverage               Ignore code coverage configuration
+  --dump-xdebug-filter <file> Generate script to set Xdebug code coverage filter
 
 Logging Options:
 

tests/unit/Util/XDebugFilterScriptGeneratorTest.php

@@ -0,0 +1,75 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Util;
+
+use PHPUnit\Framework\TestCase;
+
+class XDebugFilterScriptGeneratorTest extends TestCase
+{
+    /**
+     * @covers \PHPUnit\Util\XDebugFilterScriptGenerator::generate
+     *
+     * @dataProvider scriptGeneratorTestDataProvider
+     */
+    public function testReturnsExpectedScript(array $filterConfiguration, array $resolvedWhitelist)
+    {
+        $writer = new XDebugFilterScriptGenerator();
+        $actual = $writer->generate($filterConfiguration, $resolvedWhitelist);
+
+        $this->assertStringEqualsFile(__DIR__ . '/_files/expectedXDebugFilterScript.txt', $actual);
+    }
+
+    public function scriptGeneratorTestDataProvider(): array
+    {
+        return [
+            [
+                [
+                    'include' => [
+                        'directory' => [
+                            [
+                                'path'   => 'src/somePath',
+                                'suffix' => '.php',
+                                'prefix' => '',
+                            ],
+                        ],
+                        'file' => [
+                            'src/foo.php',
+                            'src/bar.php',
+                        ],
+                    ],
+                    'exclude' => [
+                        'directory' => [],
+                        'file'      => [],
+                    ],
+                ],
+                [],
+                __DIR__ . '/_files/expectedXDebugFilterScript.php',
+            ],
+            [
+                [
+                    'include' => [
+                        'directory' => ['src/'],
+                        'file'      => ['src/foo.php'],
+                    ],
+                    'exclude' => [
+                        'directory' => [],
+                        'file'      => ['src/baz.php'],
+                    ],
+                ],
+                [
+                    'src/somePath',
+                    'src/foo.php',
+                    'src/bar.php',
+                ],
+                __DIR__ . '/_files/expectedXDebugFilterScript.php',
+            ],
+        ];
+    }
+}

tests/unit/Util/_files/expectedXDebugFilterScript.txt

@@ -0,0 +1,14 @@
+<?php
+if (!\function_exists('xdebug_set_filter')) {
+    return;
+}
+
+xdebug_set_filter(
+    XDEBUG_FILTER_CODE_COVERAGE,
+    XDEBUG_PATH_WHITELIST,
+    [
+        'src/somePath',
+        'src/foo.php',
+        'src/bar.php'
+    ]
+);