pakeFinder

Introduction

pakeFinder is the utility class, which allows you to define rules, which describe set of files. Most of the Pake’s helpers which deal with files expect pakeFinder objects as their input.

Some examples:

<?php
    // all directories, which start with "a" letter
    $rule = pakeFinder::type('directory')->name('a*');
    
    // all files, which names consist of digits,
    // ignoring meta-data related to version-control systems
    // returned paths should be returned as relative to root of search
    $rule = pakeFinder::type('file')->name('/^[0-9]+/$')
                                    ->ignore_version_control()
                                    ->relative();
?>

So, to delete all files from “/tmp” folder, which match the rule, you’ll need to use the following code:

<?php
pake_remove($rule, '/tmp');
?>

If you need to get a list of paths for some custom processing, you can do that using in() method:

<?php
$paths = $rule->in('/tmp');
?>

API

Constructing

::type(string $type)

This is a factory method, which prepares new pakeFinder objects. $type parameter specifies type of filesystem objects to return; can be: “file”, “directory” or “any”

<?php
$rule = pakeFinder::type('any');
?>

Rules refinement

All methods described in this section modify pakeFinder object and return the same pakeFinder object, which allows easy chaining of methods.

→maxdepth($level)

Finder will descend at most $level levels of directories below the starting point.

→mindepth($level)

Finder will start applying tests at level $level.

→name(…)

Adds rules that files must match. You can use patterns (delimited with ‘/’ sign), globs or simple strings.

<?php
    $finder->name('*.php');
    $finder->name('/\.php$/'); // same as above
    $finder->name('test.php');
?>

Several patterns can be specified in a single method-call:

<?php
    $finder->name('*.php', '*.html');
?>

→not_name(…)

Adds rules that files must not match.

<?php
    $finder->name('*.php', '*.html')->not_name('debug.php', 'phpinfo.php', 'test.html');
?>

→size(…)

This method allows you to create rule, which limits set of files by size parameter.

Size rule is a string, which consists of comparator, number and optional magnitude.

Allowed comparators:

• == (empty comparator is treated as ‘==’ also)
• >
• >=
• <
• <=

Allowed magnitudes (case insensitive):

• k — kilo (1000)
• m — mega (1000000)
• g – giga (1000000000)
• ki — kibi (1024)
• mi — mebi (1024²)
• gi — gibi (1024³)

<?php
    $finder->size('>1Ki', '<10Mi'); // more thab kibibyte, but less than 10 mebibytes
?>

→prune(…)

If pakeFinder detects path component which matches rules specified by this directive it won’t traverse tree deeper beyond this point

<?php
    // we are interested only in "imgs" directories, and only in the upper-level of these directories
    // if there is "imgs/abs/imgs" directory, we don't need it
    pakeFinder::type('directory')->name('imgs')->prune('imgs');
?>

→discard(…)

pakeFinder will remove all paths, which match rules specified by this directive from recordset

<?php
    pakeFinder::type('file')->discard('.htaccess', '.DS_Store');
?>

→ignore_version_control()

helps to remove all known version control systems’ metadata from resultset. Currently supports subversion, CVS, DARCS, Gnu Arch, Monotone, Bazaar-NG. Git, Mercurial

<?php
    pakeFinder::type('any')->ignore_version_control();
?>

→exec(…)

You can specify any number of callbacks as arguments of this method. Each of those will be executed just before pakeFinder will return it’s resultset. This way, it is possible to add custom filters to the chain.

If callback returns FALSE, item is removed from recordset.

callbacks’ signature:

<?php
    function my_filter($dir, $entry)
    {
        return ('/tmp' == $dir and strlen($entry) > 5);
    }

    $rule = pakeFinder::type('any')->exec('my_filter');

    $results1 = $rule->in('/tmp');
    $results2 = $rule->in('/home');
?>

→relative()

By default, pakeFinder returns absolute paths in it’s resultset. If you are interested in relative paths — use this modifier.

→follow_link()

By default, pakeFinder doesn’t follow symlinks. If you want it to follow them — use this modifier.

Getting resultset

→in(…)

This method takes strings, which will be used as roots of search and returns array of paths, which match set of rules specified before.

<?php
    $rule = pakeFinder::type('any');
    
    // return all matches in "/tmp"
    $result1 = $rule->in('/tmp');
    
    // return all matches in "/home/foo" and "/home/bar" as relative paths
    $result2 = $rule->relative()->in('/home/foo', '/home/bar');
?>