Add doc

Author: dantleech

src/Util/FileMatcher.php

@@ -13,14 +13,18 @@
 use function array_pop;
 use function count;
 use function ctype_alpha;
-use function preg_match;
 use function preg_quote;
 use function sprintf;
 use function strlen;
-use function substr;
 use RuntimeException;
 
 /**
+ * FileMatcher attempts to emulate the behavior of PHP's glob function on file
+ * paths based on POSIX.2.
+ *
+ * - https://en.wikipedia.org/wiki/Glob_(programming)
+ * - https://man7.org/linux/man-pages/man7/glob.7.html
+ *
  * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
  *
  * @internal This class is not covered by the backward compatibility promise for PHPUnit
@@ -43,27 +47,13 @@
     private const T_COLON           = 'colon';
     private const T_CHAR_CLASS      = 'char_class';
 
-    public static function match(string $path, FileMatcherPattern $pattern): bool
-    {
-        self::assertIsAbsolute($path);
-
-        $regex = self::toRegEx($pattern->path);
-
-        return preg_match($regex, $path) !== 0;
-    }
-
     /**
-     * Based on webmozart/glob.
-     *
-     * @return string the regular expression for matching the glob
+     * Compile a regex for the given glob.
      */
-    public static function toRegEx($glob, $flags = 0): string
+    public static function toRegEx(string $glob): FileMatcherRegex
     {
-        self::assertIsAbsolute($glob);
-
         $tokens = self::tokenize($glob);
-
-        $regex = '';
+        $regex  = '';
 
         foreach ($tokens as $token) {
             $type = $token[0];
@@ -84,24 +74,15 @@ public static function toRegEx($glob, $flags = 0): string
                 self::T_BRACKET_CLOSE   => ']',
                 self::T_HYPHEN          => '-',
                 self::T_CHAR_CLASS      => '[:' . $token[1] . ':]',
-                default                 => '',
+                default                 => throw new RuntimeException(sprintf(
+                    'Unhandled token type: %s - this should not happen',
+                    $type,
+                )),
             };
         }
         $regex .= '(/|$)';
-        dump($tokens);
-        dump($regex);
 
-        return '{^' . $regex . '}';
-    }
-
-    private static function assertIsAbsolute(string $path): void
-    {
-        if (substr($path, 0, 1) !== '/') {
-            throw new RuntimeException(sprintf(
-                'Path "%s" must be absolute',
-                $path,
-            ));
-        }
+        return new FileMatcherRegex('{^' . $regex . '}');
     }
 
     /**

src/Util/FileMatcherRegex.php

@@ -0,0 +1,39 @@
+<?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 function preg_match;
+use function sprintf;
+use function substr;
+use RuntimeException;
+
+final class FileMatcherRegex
+{
+    public function __construct(private string $regex)
+    {
+    }
+
+    public function matches(string $path): bool
+    {
+        self::assertIsAbsolute($path);
+
+        return preg_match($this->regex, $path) !== 0;
+    }
+
+    private static function assertIsAbsolute(string $path): void
+    {
+        if (substr($path, 0, 1) !== '/') {
+            throw new RuntimeException(sprintf(
+                'Path "%s" must be absolute',
+                $path,
+            ));
+        }
+    }
+}

tests/unit/Util/FileMatcherTest.php

@@ -612,7 +612,7 @@ public function testExceptionIfPathIsNotAbsolute(): void
     {
         $this->expectException(RuntimeException::class);
         $this->expectExceptionMessage('Path "foo/bar" must be absolute');
-        FileMatcher::match('foo/bar', new FileMatcherPattern(''));
+        FileMatcher::toRegEx('/a')->matches('foo/bar');
     }
 
     /**
@@ -621,7 +621,7 @@ public function testExceptionIfPathIsNotAbsolute(): void
     private static function assertMap(FileMatcherPattern $pattern, array $matchMap): void
     {
         foreach ($matchMap as $candidate => $shouldMatch) {
-            $matches = FileMatcher::match($candidate, $pattern);
+            $matches = FileMatcher::toRegEx($pattern->path)->matches($candidate);
 
             if ($matches === $shouldMatch) {
                 self::assertTrue(true);