Glob-like file and pattern matching utility.

Requirements

• PHP >= 7.2

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. 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)

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

Convet a glob pattern 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 also control line anchors via the $options parameter.

Pattern::make('foo')->toRegex(Glob::NO_ANCHORS); // Returns '#foo#'
Pattern::make('foo')->toRegex(Glob::START_ANCHOR); // Returns '#^foo#'
Pattern::make('foo')->toRegex(Glob::END_ANCHOR); // Returns '#foo$#'
Pattern::make('foo')->toRegex(Glob::BOTH_ANCHORS); // Returns '#^foo$#'
Pattern::make('foo')->toRegex(Glob::START_ANCHOR | Glob::END_ANCHOR); // Returns '#^foo$#'

Escape

Escape glob pattern characters from a string.

Pattern::escape('What?'); // Returns 'What\?'
Pattern::escape('*.{yml,yaml}'); // Returns '\*.\{yml\,yaml\}'
Pattern::escape('[Gg]l*b.txt'); // Returns '\[Gg\]l\*b.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 Twitter.

Please report bugs to the GitHub Issue Tracker.

Copyright

This project is licensed under the MIT License.