phlak / glob
Glob-like pattern matching and utilities
Requires
- php: >=8.0
- symfony/finder: ^6.0
Requires (Dev)
- phlak/coding-standards: ^2.0
- phpstan/phpstan: ^1.9
- phpunit/phpunit: ^9.0
- psy/psysh: ^0.11
- symfony/var-dumper: ^6.0
- yoast/phpunit-polyfills: ^1.0
This package is auto-updated.
Last update: 2023-07-01 00:05:34 UTC
README
Glob-like file and pattern matching utility.
Requirements
- PHP >= 8.0
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
orc
)[a-c]
matches a single character in the range (i.e.a
,b
orc
)[^abc]
matches any character not in the set (i.e. nota
,b
orc
)[^a-c]
matches any character not in the range (i.e. nota
,b
orc
){foo,bar,baz}
matches any pattern in the set (i.e.foo
,bar
orbaz
)- 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.