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.
$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,borc)[a-c]matches a single character in the range (i.e.a,borc)[^abc]matches any character not in the set (i.e. nota,borc)[^a-c]matches any character not in the range (i.e. nota,borc){foo,bar,baz}matches any pattern in the set (i.e.foo,barorbaz)- Sets may contain other matching patterns (i.e.
{foo,ba[rz]})
- Sets may contain other matching patterns (i.e.
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 containsfoo(!foo)matches any string that does not also containfoo
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 $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$#'
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 Twitter.
Please report bugs to the GitHub Issue Tracker.
Copyright
This project is licensed under the MIT License.
290 Dec 26, 2022
31.1k Dec 30, 2022
7 Aug 24, 2022
3 Jan 3, 2023
169 Jul 28, 2022
27 Jan 1, 2023
18 Oct 7, 2022
909 Dec 22, 2022
1 Jan 2, 2022
112 Feb 15, 2022
134 Dec 26, 2022
798 Jan 8, 2023
13 Nov 26, 2022
474 Dec 31, 2022
240 Jul 18, 2022
14 May 24, 2022
7.4k Jan 5, 2023
195 Dec 17, 2022
314 Dec 2, 2022