README

Glob-like file and pattern matching utility.

Requirements

PHP >= 8.1

Installation

Install Splat with Composer.

composer require phlak/splat

Then import the Glob or Pattern classes as needed.

use PHLAK\Splat\Glob;
use PHLAK\Splat\Pattern;

Patterns

Glob methods accept a $pattern as the first parameter. This can be a string or an instance of \PHLAK\Splat\Pattern.

$pattern = new Pattern(...);
$pattern = Pattern::make(...);

A pattern string may contain one or more of the following special matching expressions.

Matching Expressions

? matches any single character
* matches zero or more characters excluding / (\ on Windows)
** matches zero or more characters including / (\ on Windows)
[abc] matches a single character from the set (i.e. a, b or c)
[a-c] matches a single character in the range (i.e. a, b or c)
[!abc] matches any character not in the set (i.e. not a, b or c)
[!a-c] matches any character not in the range (i.e. not a, b or c)
{foo,bar,baz} matches any pattern in the set (i.e. foo, bar or baz)
- Sets may contain other matching patterns (i.e. {foo,ba[rz]})

Assertions

The following assertions can be use to assert that a string is followed by, or not followed by, another pattern.

(=foo) matches any string that also contains foo
(!foo) matches any string that does not also contain foo

For example, a pattern of *.tar(!.{gz,xz}) will match a string ending with .tar or .tar.bz but not tar.gz or tar.xz.

Converting Patterns To Regular Expressions

Glob patterns can be converted to a regular expression pattern.

Pattern::make('foo')->toRegex(); // Returns '#^foo$#'
Pattern::make('foo/bar.txt')->toRegex(); // Returns '#^foo/bar\.txt$#'
Pattern::make('file.{yml,yaml}')->toRegex(); // Returns '#^file\.(yml|yaml)$#'

You can control regular expression line anchors via the $anchors parameter.

use PHLAK\Splat\Anchors;
use PHLAK\Splat\Pattern;

Pattern::make('foo')->toRegex(Anchors::NONE); // Returns '#foo#'
Pattern::make('foo')->toRegex(Anchors::START); // Returns '#^foo#'
Pattern::make('foo')->toRegex(Anchors::END); // Returns '#foo$#'
Pattern::make('foo')->toRegex(Anchors::BOTH); // Returns '#^foo$#'

Pattern Character Escaping

Sometimes you may have characters in a string that shouldn't be treated as matching expression characters. In those situations you can escape any character by preceeding it with a backslash (\).

Pattern::make('What is happening\?');
Pattern::make('Wall-E \[2008\].mp4');

You may also escape glob pattern characters from a string programmatically with the Pattern::escape() method.

Pattern::escape('What is happening?'); // Returns 'What is happening\?'
Pattern::escape('*.{yml,yaml}'); // Returns '\*.\{yml\,yaml\}'
Pattern::escape('[Ss]pl*t.txt'); // Returns '\[Ss\]pl\*t.txt'

Methods

Files In

Get a list of files in a directory matching a glob pattern.

Glob::in('**.txt', 'some/file/path');

Returns a Symfony Finder Component containing the files matching the glob pattern within the specified directory (e.g. foo.txt, foo/bar.txt, foo/bar/baz.txt, etc.).

Exact Match

Test if a string matches a glob pattern.

Glob::match('*.txt', 'foo.txt'); // true
Glob::match('*.txt', 'foo.log'); // false

Match Start

Test if a string starts with a glob pattern.

Glob::matchStart('foo/*', 'foo/bar.txt'); // true
Glob::matchStart('foo/*', 'bar/foo.txt'); // false

Match End

Test if a string ends with a glob pattern.

Glob::matchEnd('**.txt', 'foo/bar.txt'); // true
Glob::matchEnd('**.txt', 'foo/bar.log'); // false

Match Within

Test if a string contains a glob pattern.

Glob::matchWithin('bar', 'foo/bar/baz.txt'); // true
Glob::matchWithin('bar', 'foo/baz/qux.txt'); // false

Filter an Array (of Strings)

Filter an array of strings to values matching a glob pattern.

Glob::filter('**.txt', [
    'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
]);

// Returns ['foo.txt', 'foo/bar.txt']

Reject an Array (of Strings)

Filter an array of strings to values not matching a glob pattern.

Glob::reject('**.txt', [
    'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
]);

// Returns ['foo', 'bar.zip', 'foo/bar.png']

Changelog

A list of changes can be found on the GitHub Releases page.

Troubleshooting

For general help and support join our GitHub Discussion or reach out on Bluesky.

Please report bugs to the GitHub Issue Tracker.

Copyright

This project is licensed under the MIT License.

phlak / splat

Maintainers

Details