--- Glob-like file and pattern matching utility. Requirements ------------ - [PHP](https://www.php.net/) >= 8.1 Installation ------------ Install Splat with Composer. composer require phlak/splat Then import the `Glob` or `Pattern` classes as needed. ```php 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`. ```php $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. ```php 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. ```php 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 (`\`). ```php 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. ```php 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. ```php Glob::in('**.txt', 'some/file/path'); ``` Returns a [Symfony Finder Component](https://symfony.com/doc/current/components/finder.html) 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. ```php Glob::match('*.txt', 'foo.txt'); // true Glob::match('*.txt', 'foo.log'); // false ``` --- ### Match Start Test if a string starts with a glob pattern. ```php 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. ```php Glob::matchEnd('**.txt', 'foo/bar.txt'); // true Glob::matchEnd('**.txt', 'foo/bar.log'); // false ``` --- ### Match Within Test if a string contains a glob pattern. ```php 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. ```php 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. ```php 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](https://github.com/PHLAK/Splat/releases) page. Troubleshooting --------------- For general help and support join our [GitHub Discussion](https://github.com/PHLAK/Splat/discussions) or reach out on [Twitter](https://twitter.com/PHLAK). Please report bugs to the [GitHub Issue Tracker](https://github.com/PHLAK/Splat/issues). Copyright --------- This project is licensed under the [MIT License](https://github.com/PHLAK/Splat/blob/master/LICENSE).