feat: Add case sensitivity option for path matching

Author: roxblnfk

README.md

@@ -97,9 +97,12 @@ $path->match('file?.txt');       // matches file1.txt, fileA.txt, etc.
 $path->match('file[123].txt');   // matches file1.txt, file2.txt, file3.txt
 $path->match('test/*/*.php');    // matches test/any/file.php
 
-// Case sensitivity depends on the operating system
-// Windows: case-insensitive (File.TXT matches *.txt)
-// Unix/Linux: case-sensitive (File.TXT does NOT match *.txt)
+// Control case sensitivity with optional parameter
+$file = Path::create('File.TXT');
+$file->match('*.txt');              // OS default (case-insensitive on Windows, case-sensitive on Unix)
+$file->match('*.txt', false);       // case-insensitive (matches on any OS)
+$file->match('*.txt', true);        // case-sensitive (won't match - different case)
+$file->match('*.TXT', true);        // case-sensitive (matches - exact case)
 ```
 
 ## Edge cases and special handling

src/Path.php

@@ -203,13 +203,21 @@ public function absolute(): self
      *
      * @param non-empty-string|self $pattern The pattern to match against. Can be a string path or Path object.
      *        Will be converted to absolute path before matching.
+     * @param bool|null $caseSensitive Whether the match should be case-sensitive. If null, uses OS default:
+     *        case-insensitive on Windows, case-sensitive on Unix/Linux.
      *
      * @return bool True if the path matches the pattern, false otherwise.
      */
-    public function match(string|self $pattern): bool
+    public function match(string|self $pattern, ?bool $caseSensitive = null): bool
     {
+        // Use OS default: case-insensitive on Windows, case-sensitive on Unix
+        $caseSensitive ??= \DIRECTORY_SEPARATOR !== '\\';
+
         \is_string($pattern) and $pattern = self::create($pattern);
-        return \fnmatch((string) $pattern->absolute(), $this->absolute()->path, \FNM_NOESCAPE);
+
+        $flags = $caseSensitive ? \FNM_NOESCAPE : \FNM_NOESCAPE | \FNM_CASEFOLD;
+
+        return \fnmatch((string) $pattern->absolute(), $this->absolute()->path, $flags);
     }
 
     /**

tests/Unit/PathTest.php

@@ -535,4 +535,66 @@ public function testMatchCaseSensitive(): void
             Assert::false($result, 'On Unix, match should be case-sensitive');
         }
     }
+
+    public function testMatchWithCaseSensitiveFlag(): void
+    {
+        // Arrange
+        $path = Path::create('Test/File.TXT')->absolute();
+        $pattern = 'test/file.txt';
+
+        // Act & Assert - case-sensitive matching
+        Assert::false($path->match($pattern, true), 'Should not match when case-sensitive is true');
+
+        // Act & Assert - case-insensitive matching
+        Assert::true($path->match($pattern, false), 'Should match when case-sensitive is false');
+    }
+
+    public function testMatchWithCaseSensitiveFlagExactCase(): void
+    {
+        // Arrange
+        $path = Path::create('Test/File.TXT')->absolute();
+        $patternExact = 'Test/File.TXT';
+        $patternLower = 'test/file.txt';
+
+        // Act & Assert - exact case with case-sensitive flag
+        Assert::true($path->match($patternExact, true), 'Should match exact case with case-sensitive flag');
+
+        // Act & Assert - different case with case-sensitive flag
+        Assert::false($path->match($patternLower, true), 'Should not match different case with case-sensitive flag');
+    }
+
+    public function testMatchCaseInsensitiveOnAllOS(): void
+    {
+        // Arrange
+        $path = Path::create('Documents/FILE.txt')->absolute();
+
+        // Act & Assert - force case-insensitive on any OS
+        Assert::true($path->match('*/file.TXT', false), 'Should match with case-insensitive flag');
+        Assert::true($path->match('*/FILE.txt', false), 'Should match with case-insensitive flag');
+        Assert::true($path->match('*/FiLe.TxT', false), 'Should match with case-insensitive flag');
+    }
+
+    public function testMatchCaseSensitiveOnAllOS(): void
+    {
+        // Arrange
+        $path = Path::create('Documents/report.PDF')->absolute();
+
+        // Act & Assert - force case-sensitive on any OS
+        Assert::true($path->match('*/report.PDF', true), 'Should match exact case');
+        Assert::false($path->match('*/report.pdf', true), 'Should not match different case');
+        Assert::false($path->match('*/REPORT.PDF', true), 'Should not match different case');
+    }
+
+    public function testMatchWithWildcardsAndCaseFlag(): void
+    {
+        // Arrange
+        $path = Path::create('src/Controller/UserController.php')->absolute();
+
+        // Act & Assert - wildcards with case-insensitive
+        Assert::true($path->match('*/controller/*.PHP', false), 'Wildcard should match case-insensitive');
+
+        // Act & Assert - wildcards with case-sensitive
+        Assert::false($path->match('*/controller/*.php', true), 'Should not match - Controller != controller');
+        Assert::true($path->match('*/Controller/*.php', true), 'Should match with correct case');
+    }
 }