nette / finder
🔍 Nette Finder: find files and directories with an intuitive API.
Installs: 20 935 438
Dependents: 262
Suggesters: 0
Security: 0
Stars: 733
Watchers: 40
Forks: 16
Open Issues: 0
Requires
- php: >=7.1
- nette/utils: ^2.4 || ^3.0
Requires (Dev)
- nette/tester: ^2.0
- phpstan/phpstan: ^0.12
- tracy/tracy: ^2.3
Conflicts
- nette/nette: <2.2
This package is auto-updated.
Last update: 2021-01-08 20:38:00 UTC
README
Introduction
Nette Finder makes browsing the directory structure really easy.
Documentation can be found on the website. If you like it, please make a donation now. Thank you!
Installation:
composer require nette/finder
All examples assume the following class alias is defined:
use Nette\Utils\Finder;
Searching for Files
How to find all *.txt
files in $dir
directory and all its subdirectories?
foreach (Finder::findFiles('*.txt')->from($dir) as $key => $file) { // $key is a string containing absolute filename with path // $file is an instance of SplFileInfo }
The files in the $file
variable are instances of the SplFileInfo
class.
If the directory does not exist, an Nette\UnexpectedValueException
is thrown.
And what about searching for files in a directory without subdirectories? Instead of from()
use in()
:
Finder::findFiles('*.txt')->in($dir)
Search by multiple masks and even multiple directories at once:
Finder::findFiles('*.txt', '*.php') ->in($dir1, $dir2) // or from($dir1, $dir2)
Parameters can also be arrays:
Finder::findFiles(['*.txt', '*.php']) ->in([$dir1, $dir2]) // or from([$dir1, $dir2])
Depth of search can be limited using the limitDepth()
method.
Searching for Directories
In addition to files, it is possible to search for directories using Finder::findDirectories('subdir*')
.
Or to search for files and directories together using Finder::find('*.txt')
, the mask in this case only applies to files. When searching recursively with from()
, the subdirectory is returned first, followed by the files in it, which can be reversed with childFirst()
.
Mask
The mask does not have to describe only the file name, but also the path. Example: searching for *.jpg
files located in a subdirectory starting with imag
:
Finder::findFiles('imag*/*.jpg')
Thus, the known wildcards *
and ?
represent any characters except the directory separator /
. The double **
represents any characters, including the directory separator:
Finder::findFiles('imag**/*.jpg') // finds also image/subdir/file.jpg
In addition you can use in the mask ranges [...]
or negative ranges [!...]
known from regular expressions. Searching for *.txt
files containing a digit in the name:
Finder::findFiles('*[0-9]*.txt')
Excluding
Use exclude()
to pass masks that the file must not match. Searching for *.txt
files, except those containing 'X
' in the name:
Finder::findFiles('*.txt') ->exclude('*X*')
If exclude()
is specified after from()
, it applies to crawled subdirectories:
Finder::findFiles('*.php') ->from($dir) ->exclude('temp', '.git')
Filtering
You can also filter the results, for example by file size. Here's how to find files of size between 100 and 200 bytes:
Finder::findFiles('*.php') ->size('>=', 100) ->size('<=', 200) ->from($dir)
Filtering by date of last change. Example: searching for files changed in the last two weeks:
Finder::findFiles('*.php') ->date('>', '- 2 weeks') ->from($dir)
Both functions understand the operators >
, >=
, <
, <=
, =
, !=
.
Here we traverse PHP files with number of lines greater than 1000. As a filter we use a custom callback:
$hasMoreThan100Lines = function (SplFileInfo $file): bool { return count(file($file->getPathname())) > 1000; }; Finder::findFiles('*.php') ->filter($hasMoreThan100Lines)
Handy, right? You will certainly find a use for Finder in your applications.