Manual

Commonly needed functions to search for files and directories

Search methods

Search methods – Types of methods what can be used in search functions

Search methods and their patterns

All search functions use $pattern parameter to specify match for filenames. Format of the $pattern depends on value of another parameter - $pattern_type.

If value of $pattern_type is 'php', then the pattern is case-sensitive string which follows the conventions of the ereg_*-functions.
In case of 'perl' pattern type it must follow the preg_*-functions pattern format. It is recommended to use 'perl', because it is faster.
The last 'shell' mode is most simple and should be familiar to everybody with basic computer skills. It is as easy as windows approach, but has some additional concepts borrowed from the FAR Manager software. The text of the following section was borrowed from the FAR Manager documentation.

'shell' search mode file masks

File masks are used to select single files and folders or groups of them. Masks may contain common valid file name symbols, wildcards ('*' and '?') and special expressions:

*
any number of characters;
?
any single character;
[c,x-z]
any character enclosed by the brackets. Both separate characters and character intervals are allowed.

For example, files ftp.exe, fc.exe and f.ext may be selected using mask f*.ex?, mask *co* will select both color.ini and edit.com, mask [c-f,t]*.txt can select config.txt, demo.txt, faq.txt and tips.txt.

You may enter several file masks separated with commas or semicolons. For example, to select all the documents, you can specify *.doc,*.txt,*.wri in search pattern.

You may use exclude masks. An exclude mask is one or multiple file masks that must not be matched by the files matching the mask. The exclude mask is delimited from the main mask by the character '|'.

Usage examples of exclude masks:

*.cpp All files with the extension cpp.
*.*|*.bak,*.tmp All files except for the files with extensions bak and tmp.
*.*| This mask has an error - the character | is entered, but the mask itself is not specified.
*.*|*.bak|*.tmp Also an error - the character | may not be contained in the mask more than once.
|*.bak The same as *|*.bak

The comma (or semicolon) is used for separating file masks from each other, and the '|' character separates include masks from exclude masks.

'shell' match mode is available from version 1.2.0 of File_Find

File_Find::glob()

File_Find::glob() – find matches for a pattern in a directory

Synopsis

require_once 'File/Find.php';

array &File_Find::glob ( string $pattern , string $dirpath , string $pattern_type = 'php' )

Description

Search the directory to find matches for the specified pattern.

Parameter

$pattern - a string containing the pattern to search the directory for.
$dirpath - a string containing the directory path to search.
$pattern_type - a string containing the type of pattern matching functions to use (can either be 'php', 'perl' or 'shell'). The format of the $pattern depends on the $pattern_type-value. For more information see search methods

Return value

array - an array contains all filenames and name of subdirectories, which matches the pattern. Or a PEAR_Error.

Throws

Possible PEAR_Error values
Error code	Error message	Reason	Solution
NULL	" Cannot open directory "	The given directory could not be opend.	Check typing and directory permissions. This can not be caused by a competive processing the archive with Archive_Tar

Note

This function can be called statically.

Example

Find all PHP files in current directory

<?php
include "File/Find.php";

$dir = ".";
$items = &File_Find::glob( '!.*\.php$!', $dir, 'perl' );

print_r($items);
?>

File_Find::maptree()

File_Find::maptree() – create a view map for a directory

Synopsis

require_once 'File/Find.php';

array &File_Find::maptree ( string $directory )

Description

Map the directory tree given by the directory_path parameter.

Parameter

string $directory - contains the directory path that you want to map

Return value

array - a two element array, the first element containing a list of all the directories, the second element containing a list of all the files.

Note

This function can be called statically.

Example

Get the map of a directory

<?php
include "File/Find.php";

$dir = "File_Find";
list($directories, $files) = File_Find::maptree($dir);

echo "Directories ";
print_r($directories);

echo "Files ";
print_r($files);
?>

The above example will output something similar to:


Directories Array
(
    [0] => File_Find
    [1] => File_Find\dir2
    [2] => File_Find\dir2\2
    [3] => File_Find\dir2\1
    [4] => File_Find\dir2\0
    [5] => File_Find\dir
    [6] => File_Find\dir\txtdir
    [7] => File_Find\dir\dir3
    [8] => File_Find\dir\dir2
)
Files Array
(
    [0] => File_Find\dir2\2\1.txt
    [1] => File_Find\dir2\1\1.txt
    [2] => File_Find\dir2\0\1.txt
    [3] => File_Find\dir\1.txt
    [4] => File_Find\dir\2.txt
    [5] => File_Find\dir\txtdir\5.txt
    [6] => File_Find\dir\dir3\4.bak
    [7] => File_Find\dir\dir3\4.txt
    [8] => File_Find\dir\dir2\3.bak
    [9] => File_Find\dir\dir2\3.txt
)

File_Find::mapTreeMultiple()

File_Find::mapTreeMultiple() – create a recursive view map for a directory

Synopsis

require_once 'File/Find.php';

array &File_Find::mapTreeMultiple ( string $directory , integer $maxrecursion = 0 , integer $count = 0 )

Description

Map the directory tree given by the directory_path parameter. Depending on maxrecursion you get the content of the directory and the content of the subdirectories too.

Parameter

string $directory - contains the directory path that you want to map
integer $maxrecursion - defines the deep of recursive mapping of subdirectories
integer $count - can be ignored - internal parameter to track recursion level

Return value

array - a multidimensional array containing all subdirectories and their files

Note

This function can be called statically.

Example

Get the content of a directory including the content of subdirectories

<?php
include "File/Find.php";

$file = File_Find::mapTreemultiple('/usr/', 1);

print_r($file);
?>

The above example will output something similar to:


Array
(
   [0] => file1.tmp
   [1] => file2.tmp
   ['bin'] => Array
      (
         [0] => readme.txt
      )
)

File_Find::search()

File_Find::search() – find matches for a pattern in a directory

Synopsis

require_once 'File/Find.php';

array &File_Find::search ( string $pattern , string $dirpath , string $pattern_type = 'php' , bool $fullpath = true , string $match = 'files' )

Description

Search the directory to find matches for the specified pattern.

Parameter

$pattern - a string containing the pattern to search the directory for.
$dirpath - a string containing the directory path to search.
$pattern_type - a string containing the type of pattern matching functions to use (can either be 'php', 'perl' or 'shell'). The format of the $pattern depends on the $pattern_type-value. For more information see search methods
$fullpath - whether the string should be matched against the full path or only against the filename
$match - can be either 'files', 'directories' or 'both' to specify the kind of list to return

Return value

array - an array containing all filenames

Note

This function can be called statically.

See

File_Find::glob()