Class List
- App\Middleware\Cors
- App\Middleware\Auth
- App\Middleware\Env
- AppMin
- Application
- Route
- Data\Database
- Data\Db2Database
- Data\OdbcDatabase
- Data\Validator
- Data\KeyValue\SqliteStorage
- Data\Log\FileLogger
- Data\Log\HtmlLogger
- Encoding\Base64Url
- Encoding\Json
- Encoding\Utf8
- Environment\DotEnv
- Environment\System
- FileSystem\Search
- FileSystem\Security
- FileSystem\Sync
- Lang\I18N
- Lang\L10N
- Lang\Time
- Media\Image
- Net\Config
- Net\Email
- Net\HttpClient
- Net\HttpResponse
- Net\IP
- Net\SmtpClient
- Security\Crypto
- Security\Password
- Security\Crypto\Encryption
- Security\Crypto\FileEncryption
- Security\Crypto\JWT
- Security\Crypto\PublicKey
- Security\Crypto\Random
- Security\Crypto\SignedData
- Security\Web\CsrfSession
- Security\Web\CsrfStateless
- Security\Web\RateLimit
- Web\Request
- Web\Response
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
Search for Files and Directories (Folders)
// 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