FastSitePHP\FileSystem\Search

File System Search

This Class has functions for searching the local file system for files and directories. Additionally URL Lists can be built from a list of files.

This class works by setting the root search directory/folder [dir()], setting various search options, and then calling one of [files(), dirs(), all(), or urlFiles($url_root)] functions.

Source Code

Example Code

// Create a FileSystem Search Object
$search = new \FastSitePHP\FileSystem\Search();

// For basic usage specify a root directory with the [dir()] command and then
// call either [files()] or [dirs()]. An array of matching names will be returned.
$files = $search->dir($dir_path)->files();

// [all()] can be used to return both directories and files
list($dirs, $files) = $search->dir($dir_path)->all();

// Functions are chainable so breaking them up
// one per line can make the code easier to read.
$dirs = $search
    ->dir($dir_path)
    ->dirs();

// URL lists can also be generated from matching files.
$url_root = 'http://www.example.com/';
$urls = $search
    ->dir($dir_path)
    ->urlFiles($url_root);

// A number of different criteria functions exist and can be used to filter
// the results. In this example a recursive search is used to find PHP files
// that contain the text 'FileSystem'. When a recursive search is used the
// full file paths are returned unless [includeRoot(false)] is set.
// See documentation and examples for all functions.
$files = $search
    ->dir($dir_path)
    ->recursive(true)
    ->fileTypes(['php'])
    ->includeText(['FileSystem'])
    ->files();

Methods

dir($new_value = null)

Get or set the root directory for searching.

Returns: null | string | $this

reset()

Reset all options other than the root search directory.

Returns: $this

recursive($new_value = null)

If true then sub-directories/folders will be searched when either [dirs() or files()] are called and the full path will be returned.

Defaults to false.

Returns: bool | $this

includeRoot($new_value = null)

Applies only when using [recursive(true)]. If set to false then the root search directory will be excluded from the returned file/dir list.

Defaults to true.

Returns: bool | $this

fullPath($full_path = null)

If true then then the full file paths will be returned when [dirs() or files()] are called. Defaults to false, however when [recursive(true)] is used then the value will always be true.

Returns: bool | $this

fileTypes(array $new_value = null)

Specify an array of files types to filter on when calling [files() or urlFiles()].

Example:
    $search->fileTypes(['png', 'jpg', 'svg'])

Returns: null | array | $this

includeNames(array $new_value = null)

Specify an array of files/dir names to include on when calling [dirs(), files(), or urlFiles()]. If a file/dir matches any names in the list then it will be included in the result.

Example:
    $search->includeNames(['index.php', 'app.php'])

Returns: null | array | $this

includeRegExNames(array $new_value = null)

Specify an array of regex patterns to include on when calling [dirs(), files(), or urlFiles()]. If a file/dir name matches any regex in the list then it will be included in the result.

Example:
    $search->includeRegExNames(['/^app/', '/.htm$/'])

Returns: null | array | $this

includeRegExPaths(array $new_value = null)

Specify an array of regex patterns to include on when calling [dirs(), files(), or urlFiles()]. If part of the full path matches any regex in the list then it will be included in the result.

Returns: null | array | $this

excludeNames(array $new_value = null)

Specify an array of files/dir names to exclude on when calling [dirs(), files(), or urlFiles()]. If a file/dir matches any names in the list then it will be excluded from the result.

Example:
    $search->excludeNames(['.DS_Store', 'desktop.ini'])

Returns: null | array | $this

excludeRegExNames(array $new_value = null)

Specify an array of regex patterns to exclude on when calling [dirs(), files(), or urlFiles()]. If a file/dir name matches any regex in the list then it will be excluded from the result.

Example:
    $search->excludeRegExName(['/^[.]/', '/^testing-/'])

Returns: null | array | $this

excludeRegExPaths(array $new_value = null)

Specify an array of regex patterns to exclude on when calling [dirs(), files(), or urlFiles()]. If part of the full path matches any regex in the list then it will be excluded from the result.

Returns: null | array | $this

includeText(array $new_value = null)

Specify an array of search text that matching files must contain to be included in the result. If running from a web page or web service then this option should only be used against known files because it does not exclude large files from be opened.

Example:
    $search->fileTypes(['php'])->includeText(['X-API-Key'])

By default text searches are case-insensitive which is controlled by the [caseInsensitiveText()] function.

Returns: null | array | $this

caseInsensitiveText($new_value = null)

Specify if content searches defined from [includeText()] should be case-insensitive or not.

Defaults to [true] which means that ('ABC' === 'abc').

Returns: bool | $this

hideExtensions($new_value = null)

If set to [true] then file extensions will be hidden on the result. This only applies to [files()] and requires [fullPath()] to be false.

Returns: bool | $this

files()

Returns an array of file names in a directory matching the specified criteria.

Returns: array

dirs()

Returns an array of directory names in a directory matching the specified criteria and excluding the dot directories '.' and '..'.

Returns: array

all()

Returns an array of all directory names and an array of all files names from the root directory [dir(path)] excluding the dot directories '.' and '..'.

This function does not use any search criteria so if searching for files and directories use [files()] or [dirs()] instead.

Returns: array - list($dirs, $files)

urlFiles($url_root)

Returns an array of url names for files in directory matching the specified criteria.

Currently this option doesn't work with recursive directories [option: recursive(true)].

Returns: array