findFiles()

Lists files in a directory with advanced filtering, sorting, and recursive options.

Parameters

$directory : string|null

The target directory path. If null or invalid, a DirectoryException is thrown.

$options : array{filter?: callable|null, followLinks?: bool|null, includeDots?: bool|null, mode?: string|null, order?: string|null, pattern?: string|array|null, recursive?: bool|null, sort?: callable|string|array|null} = []

Optional settings to customize the file listing.

• filter : A function to map or transform each SplFileInfo result.
• followLinks : Whether to follow symbolic links (default: false).
• includeDots : Whether to include dot files (default: false).
• mode : Filter by type: 'files', 'dirs', or 'both' (default: 'files').
• order : Sort order: 'asc' (default) or 'desc'.
• pattern : A glob pattern, regex, or list of patterns to match file names.
• recursive : Whether to search recursively (default: false).
• sort : A sort option, eg: callback, predefined string, or array of keys.

Tags

throws

DirectoryException

example

1. Basic usage: list files in directory

use function oihana\files\findFiles;
use SplFileInfo;

$files = findFiles('/var/www');

2. Recursive search

$files = findFiles('/var/www', [
'recursive' => true,
]);

3. Include dotfiles

$files = findFiles('/var/www', [
'includeDots' => true,
]);

4. Follow symbolic links (only affects recursive mode)

$files = findFiles('/var/www', [
'recursive'   => true,
'followLinks' => true,
]);

5. Filter by file name pattern (glob or regex)

$files = findFiles('/var/www', [
'pattern' => '*.php',
]);

6. Filter by multiple patterns (mixed glob + regex)

$files = findFiles('/var/www', [
'pattern' => ['*.php', '/^config\..+$/'],
]);

7. List directories only

$dirs = findFiles('/var/www', [ 'mode' => 'dirs', ]);

8. List both files and directories

$all = findFiles('/var/www', [ 'mode' => 'both' ]);

9. Custom sort: by real path

$files = findFiles('/var/www', [
'sort' => fn(SplFileInfo $a, SplFileInfo $b) => strcmp($a->getRealPath(), $b->getRealPath()),
]);

10. Predefined sort (e.g., name), descending order

$files = findFiles('/var/www', [
'sort'  => 'name',
'order' => 'desc',
]);

11. Combined sort: type then name (directories first)

$files = findFiles('/var/www', [
'sort' => ['type', 'name'],
]);

12. Map output to base names only

$names = findFiles('/var/www', [
'filter' => fn(SplFileInfo $file) => $file->getBasename(),
]);

13. Get only file sizes

$sizes = findFiles('/var/www', [
'filter' => fn(SplFileInfo $file) => $file->getSize(),
]);

14. List recursively with all options combined

$files = findFiles('/var/www',
[
    'recursive'    => true,
    'followLinks'  => true,
    'includeDots'  => true,
    'mode'         => 'files',
    'pattern'      => ['*.log', '*.txt'],
    'sort'         => 'ci_name',
    'order'        => 'asc',
    'filter'       => fn(SplFileInfo $file) => $file->getFilename(),
]);

see

sortFiles()

see

FindFindOption

see

FindMode

see

Order::asc

author

Marc Alcaraz (ekameleon)

since

1.0.0