PHP fnmatch Function
last modified April 3, 2025
The PHP fnmatch function checks if a string matches a shell wildcard
pattern. It's useful for filename matching and pattern validation.
Basic Definition
The fnmatch function tests if a string matches a given pattern. It
supports wildcards like *, ?, and character ranges like [a-z].
Syntax: fnmatch(string $pattern, string $string, int $flags = 0): bool.
The function returns true if the string matches the pattern, false otherwise.
Basic fnmatch Example
This shows the simplest usage of fnmatch with a wildcard pattern.
<?php
declare(strict_types=1);
$result = fnmatch("*.txt", "document.txt");
var_dump($result); // Outputs: bool(true)
This checks if "document.txt" matches the "*.txt" pattern. The * wildcard matches any sequence of characters, so any .txt file will match.
Question Mark Wildcard
The ? wildcard matches exactly one character in the pattern.
<?php
declare(strict_types=1);
$result1 = fnmatch("file?.txt", "file1.txt");
$result2 = fnmatch("file?.txt", "file12.txt");
var_dump($result1); // Outputs: bool(true)
var_dump($result2); // Outputs: bool(false)
The first example matches because ? matches the single "1". The second fails because ? can't match two characters. Each ? must match exactly one character.
Character Ranges
Square brackets define character ranges that match any single character within.
<?php
declare(strict_types=1);
$result1 = fnmatch("image_[0-9].jpg", "image_1.jpg");
$result2 = fnmatch("image_[0-9].jpg", "image_a.jpg");
var_dump($result1); // Outputs: bool(true)
var_dump($result2); // Outputs: bool(false)
The [0-9] range matches any single digit. The first example matches because "1" is in the range. The second fails because "a" isn't a digit.
Case Insensitive Matching
The FNM_CASEFOLD flag makes the matching case insensitive.
<?php
declare(strict_types=1);
$result = fnmatch("*.TXT", "document.txt", FNM_CASEFOLD);
var_dump($result); // Outputs: bool(true)
Without the flag, this would return false due to case mismatch. With FNM_CASEFOLD, the pattern matches regardless of case differences in the filename.
Directory Matching
fnmatch can match paths with directory separators.
<?php
declare(strict_types=1);
$result = fnmatch("/var/www/*.php", "/var/www/index.php");
var_dump($result); // Outputs: bool(true)
This checks if the full path matches the pattern. The * wildcard matches the "index" portion of the path. The function treats / characters literally in patterns.
Best Practices
- Pattern Clarity: Use simple patterns when possible.
- Performance: Complex patterns can be slow on large inputs.
- Security: Validate inputs when used in security contexts.
- Testing: Test edge cases with unusual filenames.
Source
This tutorial covered the PHP fnmatch function with practical
examples showing pattern matching in different scenarios.