Glob-like file and pattern matching utility.

Requirements

• PHP >= 7.2

Installation

composer require phlak/splat

Usage

Initialization

  use PHLAK\Splat\Glob;

  new Glob($pattern);
  // or
  Glob::pattern($pattern);

When instantiating a Glob object you must supply a $pattern string that 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)

Files In

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

  Glob::pattern('**.txt')->in('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 the glob pattern.

  Glob::pattern('*.txt')->match('foo.txt'); // true
  Glob::pattern('*.txt')->match('foo.log'); // false

Match Start

Test if a string starts with the glob pattern.

  Glob::pattern('foo/*')->matchStart('foo/bar.txt'); // true
  Glob::pattern('foo/*')->matchStart('bar/foo.txt'); // false

Match End

Test if a string ends with the glob pattern.

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

Match Within

Test if a string contains the glob pattern.

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

Filter an Array (of Strings)

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

  Glob::pattern('**.txt')->filter([
      '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 the glob pattern.

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

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

To Regular Expression

Convet the glob-like pattern to a regular expression pattern.

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

You can also control line anchors via the $options parameter.

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

Escape

Escape glob pattern characters from a string.

  Glob::escape('What?'); // Returns 'What\?'
  Glob::escape('*.{yml,yaml}'); // Returns '\*.\{yml\,yaml\}'
  Glob::escape('[Gg]l*b.txt'); // Returns '\[Gg\]l\*b.txt'

Changelog

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

Troubleshooting

For general help and support join our Spectrum Community or reach out on Twitter.

Please report bugs to the GitHub Issue Tracker.

Copyright

This project is licensed under the MIT License.