GithubHelp home page GithubHelp logo

glob's Introduction

Webmozart Glob

Latest Stable Version Total Downloads

A utility implementing Ant-like globbing.

Syntax:

  • ? matches any character
  • * matches zero or more characters, except /
  • /**/ matches zero or more directory names
  • [abc] matches a single character a, b or c
  • [a-c] matches a single character a, b or c
  • [^abc] matches any character but a, b or c
  • [^a-c] matches any character but a, b or c
  • {ab,cd} matches ab or cd

API Documentation

Comparison with glob()

Compared to PHP's native glob() function, this utility supports:

  • /**/ for matching zero or more directories
  • globbing custom stream wrappers, like myscheme://path/**/*.css
  • matching globs against path strings
  • filtering arrays of path strings by a glob
  • exceptions if the glob contains invalid syntax

Since PHP's native glob() function is much more efficient, this utility uses glob() internally whenever possible (i.e. when no special feature is used).

Installation

Use Composer to install the package:

$ composer require webmozart/glob

Usage

The main class of the package is Glob. Use Glob::glob() to glob the filesystem:

use Webmozart\Glob\Glob;

$paths = Glob::glob('/path/to/dir/*.css'); 

You can also use GlobIterator to search the filesystem iteratively. However, the iterator is not guaranteed to return sorted results:

use Webmozart\Glob\Iterator\GlobIterator;

$iterator = new GlobIterator('/path/to/dir/*.css');

foreach ($iterator as $path) {
    // ...
}

Path Matching

The package also provides utility methods for comparing paths against globs. Use Glob::match() to match a path against a glob:

if (Glob::match($path, '/path/to/dir/*.css')) {
    // ...
}

Glob::filter() filters a list of paths by a glob:

$paths = Glob::filter($paths, '/path/to/dir/*.css');

The same can be achieved iteratively with GlobFilterIterator:

use Webmozart\Glob\Iterator\GlobFilterIterator;

$iterator = new GlobFilterIterator('/path/to/dir/*.css', new ArrayIterator($paths));

foreach ($iterator as $path) {
    // ...
}

You can also filter the keys of the path list by passing the FILTER_KEY constant of the respective class:

$paths = Glob::filter($paths, '/path/to/dir/*.css', Glob::FILTER_KEY);

$iterator = new GlobFilterIterator(
    '/path/to/dir/*.css', 
    new ArrayIterator($paths),
    GlobFilterIterator::FILTER_KEY
);

Relative Globs

Relative globs such as *.css are not supported. Usually, such globs refer to paths relative to the current working directory. This utility, however, does not want to make such assumptions. Hence you should always pass absolute globs.

If you want to allow users to pass relative globs, I recommend to turn the globs into absolute globs using the Webmozart Path Utility:

use Webmozart\Glob\Glob;
use Webmozart\PathUtil\Path;

// If $glob is absolute, that glob is used without modification.
// If $glob is relative, it is turned into an absolute path based on the current
// working directory.
$paths = Glob::glob(Path::makeAbsolute($glob, getcwd());

Windows Compatibility

Globs need to be passed in canonical form with forward slashes only. Returned paths contain forward slashes only.

Escaping

The Glob class supports escaping by typing a backslash character \ before any special character:

$paths = Glob::glob('/backup\\*/*.css');

In this example, the glob matches all CSS files in the /backup* directory rather than in all directories starting with /backup. Due to PHP's own escaping in strings, the backslash character \ needs to be typed twice to produce a single \ in the string.

The following escape sequences are available:

  • \\?: match a ? in the path
  • \\*: match a * in the path
  • \\{: match a { in the path
  • \\}: match a } in the path
  • \\[: match a [ in the path
  • \\]: match a ] in the path
  • \\^: match a ^ in the path
  • \\-: match a - in the path
  • \\\\: match a \ in the path

Stream Wrappers

The Glob class supports stream wrappers:

$paths = Glob::glob('myscheme:///**/*.css');

Authors

Contribute

Contributions to the package are always welcome!

Support

If you are having problems, send a mail to [email protected] or shout out to @webmozart on Twitter.

License

All contents of this package are licensed under the MIT license.

glob's People

Contributors

webmozart avatar dependabot-preview[bot] avatar ocramius avatar firehed avatar liqrgv avatar asika32764 avatar harikt avatar tgalopin avatar

Watchers

James Cloos avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.