ZetCode

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.

basic_fnmatch.php
<?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.

question_mark.php
<?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.

character_ranges.php
<?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.

case_insensitive.php
<?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.

directory_matching.php
<?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

Source

PHP fnmatch Documentation

This tutorial covered the PHP fnmatch function with practical examples showing pattern matching in different scenarios.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all PHP Filesystem functions.