1.0.0 2013-01-16 19:23 UTC


Build Status

A simple file locator library.


The FileLocator library was created to provide file locating capabilities to a larger project. It can be used in templating engines, configuration file loaders, and more.


Add it to your list of Composer dependencies:

$ composer require herrera-io/file-locator=1.*


The library includes FileSystemLocator, which can be used to search one or more directory paths. Either a single directory path, or an array of paths may be passed to the constructor.


use Herrera\FileLocator\Locator\FileSystemLocator;

$locator = new FileSystemLocator('/path/to/dir');
$locator = new FileSystemLocator(array(
    '/path/to/dir3' // etc

$file = $locator->locate('file.ini'); // return the first "file.ini" found
$files = $locator->locate('file.ini', false); // find all named "file.ini"

You can also create your own custom file locator by implementing the interface, LocatorInterface. All locator classes bundled in the library also implement this interface, allowing drop-in replacement.


use Herrera\FileLocator\Locator\LocatorInterface;

class MyLocator implements LocatorInterface
    public function locate($file, $first = true)
        // do something to locate $file

        // if $first is true, return the first matching result
            // if nothing is found, return null

        // if $first is false, generate a list of found $file(s) and return it
            // if nothing is found, return an empty array

You may use one or more file locator classes together by using the Collection class. This can be used to chain together one or more file locators, and may be used in place of an actual file locator.


use Herrera\FileLocator\Collection;
use Herrera\FileLocator\Locator\FileSystemLocator;
use My\Library\CustomLocator;

$locators = new Collection();
$locators->add(new FileSystemLocator('/path/to/dir'));
$locators->add(new CustomLocator());

$file = $locator->locate('file.ini'); // return the first "file.ini" found
$files = $locator->locate('file.ini', false); // find all named "file.ini"