Finder: Αναζήτηση αρχείων
*************************

.[perex]
Πρέπει να βρείτε αρχεία που ταιριάζουν με μια συγκεκριμένη μάσκα; Το Finder μπορεί να σας βοηθήσει. Είναι ένα ευέλικτο και γρήγορο εργαλείο για την περιήγηση στη δομή των καταλόγων.


Εγκατάσταση:

```shell
composer require nette/utils
```

Τα παραδείγματα υποθέτουν ότι έχει δημιουργηθεί ένα ψευδώνυμο:

```php
use Nette\Utils\Finder;
```


Χρήση του .[#toc-using]
-----------------------

Αρχικά, ας δούμε πώς μπορείτε να χρησιμοποιήσετε το [api:Nette\Utils\Finder] για να εμφανίσετε τα ονόματα αρχείων με τις επεκτάσεις `.txt` και `.md` στον τρέχοντα κατάλογο:

```php
foreach (Finder::findFiles(['*.txt', '*.md']) as $name => $file) {
	echo $file;
}
```

Ο προεπιλεγμένος κατάλογος για την αναζήτηση είναι ο τρέχων κατάλογος, αλλά μπορείτε να τον αλλάξετε χρησιμοποιώντας τις μεθόδους [in() ή from() |#Where to search?].
Η μεταβλητή `$file` είναι μια περίπτωση της κλάσης [FileInfo |#FileInfo] με πολλές χρήσιμες μεθόδους. Το κλειδί `$name` περιέχει τη διαδρομή προς το αρχείο ως συμβολοσειρά.


Τι να αναζητήσετε; .[#toc-what-to-search-for]
---------------------------------------------

Εκτός από τη μέθοδο `findFiles()`, υπάρχει επίσης η μέθοδος `findDirectories()`, η οποία αναζητά μόνο καταλόγους, και η μέθοδος `find()`, η οποία αναζητά και τα δύο. Αυτές οι μέθοδοι είναι στατικές, οπότε μπορούν να κληθούν χωρίς να δημιουργηθεί μια περίπτωση. Η παράμετρος mask είναι προαιρετική, αν δεν την καθορίσετε, αναζητούνται τα πάντα.

```php
foreach (Finder::find() as $file) {
	echo $file; // τώρα εμφανίζονται όλα τα αρχεία και οι κατάλογοι
}
```

Χρησιμοποιήστε τις μεθόδους `files()` και `directories()` για να προσθέσετε τι άλλο θα αναζητήσετε. Οι μέθοδοι μπορούν να κληθούν επανειλημμένα και ένας πίνακας από μάσκες μπορεί να δοθεί ως παράμετρος:

```php
Finder::findDirectories('vendor') // όλοι οι κατάλογοι
	->files(['*.php', '*.phpt']); // καθώς και όλα τα αρχεία PHP
```

Μια εναλλακτική λύση αντί των στατικών μεθόδων είναι να δημιουργήσετε μια περίπτωση χρησιμοποιώντας το `new Finder` (το φρέσκο αντικείμενο που δημιουργείται με αυτόν τον τρόπο δεν αναζητά τίποτα) και να καθορίσετε τι θα αναζητήσετε χρησιμοποιώντας τις `files()` και `directories()`:

```php
(new Finder)
	->directories()      // όλοι οι κατάλογοι
	->files('*.php');    // καθώς και όλα τα αρχεία PHP
```

Μπορείτε να χρησιμοποιήσετε [μπαλαντέρ |#wildcards] `*`, `**`, `?` and `[...]` στη μάσκα. Μπορείτε ακόμη και να καθορίσετε σε καταλόγους, για παράδειγμα, το `src/*.php` θα αναζητήσει όλα τα αρχεία PHP στον κατάλογο `src`.

Οι συμβολικοί σύνδεσμοι θεωρούνται επίσης κατάλογοι ή αρχεία.


Πού να ψάξετε; .[#toc-where-to-search]
--------------------------------------

Ο προεπιλεγμένος κατάλογος αναζήτησης είναι ο τρέχων κατάλογος. Μπορείτε να το αλλάξετε αυτό χρησιμοποιώντας τις μεθόδους `in()` και `from()`. Όπως μπορείτε να δείτε από τα ονόματα των μεθόδων, η `in()` αναζητά μόνο τον τρέχοντα κατάλογο, ενώ η `from()` αναζητά και τους υποκαταλόγους του (αναδρομικά). Αν θέλετε να κάνετε αναδρομική αναζήτηση στον τρέχοντα κατάλογο, μπορείτε να χρησιμοποιήσετε τη μέθοδο `from('.')`.

Αυτές οι μέθοδοι μπορούν να κληθούν πολλές φορές ή μπορείτε να τους περάσετε πολλαπλές διαδρομές ως πίνακες, τότε τα αρχεία θα αναζητηθούν σε όλους τους καταλόγους. Εάν ένας από τους καταλόγους δεν υπάρχει, θα εκπέμπεται ένα `Nette\UnexpectedValueException`.

```php
Finder::findFiles('*.php')
	->in(['src', 'tests']) // αναζητά απευθείας στα src/ και tests/
	->from('vendor');      // αναζητά επίσης στους υποκαταλόγους vendor/
```

Οι σχετικές διαδρομές είναι σχετικές με τον τρέχοντα κατάλογο. Φυσικά, μπορούν να καθοριστούν και απόλυτες διαδρομές:

```php
Finder::findFiles('*.php')
	->in('/var/www/html');
```

Wildcards [wildcards |#wildcards] `*`, `**`, `?` can be used in the path. For example, you can use the path `src/*/*.php` για την αναζήτηση όλων των αρχείων PHP στους καταλόγους δεύτερου επιπέδου στον κατάλογο `src`. Ο χαρακτήρας `**`, που ονομάζεται globstar, είναι ένα ισχυρό ατού γιατί σας επιτρέπει να αναζητήσετε και υποκαταλόγους: χρησιμοποιήστε το `src/**/tests/*.php` για να αναζητήσετε όλα τα αρχεία PHP στον κατάλογο `tests` που βρίσκονται στον κατάλογο `src` ή σε οποιονδήποτε από τους υποκαταλόγους του.

Από την άλλη πλευρά, οι μπαλαντέρ `[...]` χαρακτήρες δεν υποστηρίζονται στη διαδρομή, δηλαδή δεν έχουν ιδιαίτερη σημασία για να αποφύγετε ανεπιθύμητη συμπεριφορά σε περίπτωση που αναζητήσετε για παράδειγμα `in(__DIR__)` και τυχαία εμφανιστούν στη διαδρομή χαρακτήρες `[]`.

Κατά την αναζήτηση αρχείων και καταλόγων σε βάθος, επιστρέφεται πρώτα ο γονικός κατάλογος και στη συνέχεια τα αρχεία που περιέχονται σε αυτόν, κάτι που μπορεί να αντιστραφεί με το `childFirst()`.


Άγριοι χαρακτήρες .[#toc-wildcards]
-----------------------------------

Μπορείτε να χρησιμοποιήσετε διάφορους ειδικούς χαρακτήρες στη μάσκα:

- `*` - replaces any number of arbitrary characters (except `/`)
- `**` - αντικαθιστά οποιονδήποτε αριθμό αυθαίρετων χαρακτήρων, συμπεριλαμβανομένου του `/` (δηλ. μπορεί να γίνει αναζήτηση σε πολλαπλά επίπεδα)
- `?` - replaces one arbitrary character (except `/`)
- `[a-z]` - αντικαθιστά έναν χαρακτήρα από τη λίστα χαρακτήρων σε αγκύλες
- `[!a-z]` - αντικαθιστά έναν χαρακτήρα εκτός της λίστας χαρακτήρων σε αγκύλες

Παραδείγματα χρήσης:

- `img/?.png` - αρχεία με το όνομα ενός γράμματος `0.png`, `1.png`, `x.png`, κ.λπ.
- `logs/[0-9][0-9][0-9][0-9]-[01][0-9]-[0-3][0-9].log` - αρχεία καταγραφής με τη μορφή `YYYY-MM-DD`
- `src/**/tests/*` - αρχεία στον κατάλογο `src/tests`, `src/foo/tests`, `src/foo/bar/tests` κ.ο.κ.
- `docs/**.md` - όλα τα αρχεία με την επέκταση `.md` σε όλους τους υποκαταλόγους του καταλόγου `docs`


Εξαιρώντας το .[#toc-excluding]
-------------------------------

Χρησιμοποιήστε τη μέθοδο `exclude()` για να αποκλείσετε αρχεία και καταλόγους από τις αναζητήσεις. Καθορίζετε μια μάσκα με την οποία το αρχείο δεν πρέπει να ταιριάζει. Παράδειγμα αναζήτησης αρχείων `*.txt` εκτός από εκείνα που περιέχουν το γράμμα `X` στο όνομα:

```php
Finder::findFiles('*.txt')
	->exclude('*X*');
```

Χρησιμοποιήστε το `exclude()` για να παραλείψετε τους αναζητούμενους υποκαταλόγους:

```php
Finder::findFiles('*.php')
	->from($dir)
	->exclude('temp', '.git')
```


Φιλτράρισμα .[#toc-filtering]
-----------------------------

Το Finder προσφέρει διάφορες μεθόδους για το φιλτράρισμα των αποτελεσμάτων (δηλαδή τη μείωσή τους). Μπορείτε να τις συνδυάσετε και να τις καλέσετε επανειλημμένα.

Χρησιμοποιήστε το `size()` για να φιλτράρετε με βάση το μέγεθος του αρχείου. Με αυτόν τον τρόπο, βρίσκουμε αρχεία με μέγεθος μεταξύ 100 και 200 bytes:

```php
Finder::findFiles('*.php')
	->size('>=', 100)
	->size('<=', 200);
```

Η μέθοδος `date()` φιλτράρει με βάση την ημερομηνία τελευταίας τροποποίησης του αρχείου. Οι τιμές μπορούν να είναι απόλυτες ή σχετικές με την τρέχουσα ημερομηνία και ώρα, για παράδειγμα, με αυτόν τον τρόπο μπορείτε να βρείτε αρχεία που άλλαξαν τις τελευταίες δύο εβδομάδες:

```php
Finder::findFiles('*.php')
	->date('>', '-2 weeks')
	->from($dir)
```

Και οι δύο συναρτήσεις κατανοούν τους τελεστές `>`, `>=`, `<`, `<=`, `=`, `!=`, `<>`.

Το Finder σας επιτρέπει επίσης να φιλτράρετε τα αποτελέσματα χρησιμοποιώντας προσαρμοσμένες συναρτήσεις. Η συνάρτηση λαμβάνει ένα αντικείμενο `Nette\Utils\FileInfo` ως παράμετρο και πρέπει να επιστρέψει το `true` για να συμπεριλάβει το αρχείο στα αποτελέσματα.

Παράδειγμα: Αναζήτηση για αρχεία PHP που περιέχουν τη συμβολοσειρά `Nette` (χωρίς να λαμβάνεται υπόψη η πεζότητα):

```php
Finder::findFiles('*.php')
	->filter(fn($file) => strcasecmp($file->read(), 'Nette') === 0);
```


Φιλτράρισμα βάθους .[#toc-depth-filtering]
------------------------------------------

Κατά την αναδρομική αναζήτηση, μπορείτε να ορίσετε το μέγιστο βάθος ανίχνευσης χρησιμοποιώντας τη μέθοδο `limitDepth()`. Αν ορίσετε `limitDepth(1)`, ανιχνεύονται μόνο οι πρώτοι υποκατάλογοι, `limitDepth(0)` απενεργοποιεί την ανίχνευση βάθους και η τιμή -1 ακυρώνει το όριο.

Το Finder σας επιτρέπει να χρησιμοποιήσετε τις δικές του λειτουργίες για να αποφασίσετε σε ποιον κατάλογο θα εισέλθετε κατά την περιήγηση. Η συνάρτηση λαμβάνει ένα αντικείμενο `Nette\Utils\FileInfo` ως παράμετρο και πρέπει να επιστρέψει το `true` για να εισέλθει στον κατάλογο:

```php
Finder::findFiles('*.php')
	->descentFilter($file->getBasename() !== 'temp');
```


Ταξινόμηση .[#toc-sorting]
--------------------------

Το Finder προσφέρει επίσης διάφορες λειτουργίες για την ταξινόμηση των αποτελεσμάτων.

Η μέθοδος `sortByName()` ταξινομεί τα αποτελέσματα με βάση το όνομα του αρχείου. Η ταξινόμηση είναι φυσική, δηλαδή χειρίζεται σωστά τους αριθμούς στα ονόματα και επιστρέφει π.χ. `foo1.txt` πριν από το `foo10.txt`.

Το Finder σας επιτρέπει επίσης να ταξινομήσετε χρησιμοποιώντας μια προσαρμοσμένη συνάρτηση. Λαμβάνει δύο αντικείμενα `Nette\Utils\FileInfo` ως παραμέτρους και πρέπει να επιστρέφει το αποτέλεσμα της σύγκρισης με τον τελεστή `<=>`, π.χ. `-1`, `0` nebo `1`. Για παράδειγμα, με αυτόν τον τρόπο ταξινομούμε τα αρχεία με βάση το μέγεθος:

```php
$finder->sortBy(fn($a, $b) => $a->getSize() <=> $b->getSize());
```


Πολλαπλές διαφορετικές αναζητήσεις .[#toc-multiple-different-searches]
----------------------------------------------------------------------

Εάν πρέπει να βρείτε πολλαπλά διαφορετικά αρχεία σε διαφορετικές τοποθεσίες ή που πληρούν διαφορετικά κριτήρια, χρησιμοποιήστε τη μέθοδο `append()`. Επιστρέφει ένα νέο αντικείμενο `Finder`, ώστε να μπορείτε να κάνετε αλυσιδωτές κλήσεις μεθόδων:


```php
($finder = new Finder) // αποθηκεύστε το πρώτο Finder στη μεταβλητή $finder!
	->files('*.php')   // αναζήτηση για αρχεία *.php στο src/
	->from('src')
	->append()
	->files('*.md')    // στο docs/ αναζητήστε αρχεία *.md
	->from('docs')
	->append()
	->files('*.json'); // στον τρέχοντα φάκελο αναζητήστε αρχεία *.json
```

Εναλλακτικά, μπορείτε να χρησιμοποιήσετε τη μέθοδο `append()` για να προσθέσετε ένα συγκεκριμένο αρχείο (ή έναν πίνακα αρχείων). Τότε επιστρέφει το ίδιο αντικείμενο `Finder`:

```php
$finder = Finder::findFiles('*.txt')
	->append(__FILE__);
```


FileInfo .[#toc-fileinfo]
-------------------------

Η [Nette\Utils\FileInfo |api:] είναι μια κλάση που αντιπροσωπεύει ένα αρχείο ή έναν κατάλογο στα αποτελέσματα αναζήτησης. Είναι μια επέκταση της κλάσης [SplFileInfo |php:SplFileInfo] που παρέχει πληροφορίες όπως το μέγεθος του αρχείου, την ημερομηνία τελευταίας τροποποίησης, το όνομα, τη διαδρομή κ.λπ.

Επιπλέον, παρέχει μεθόδους για την επιστροφή σχετικών διαδρομών, πράγμα που είναι χρήσιμο κατά την αναζήτηση σε βάθος:

```php
foreach (Finder::findFiles('*.jpg')->from('.') as $file) {
	$absoluteFilePath = $file->getRealPath();
	$relativeFilePath = $file->getRelativePathname();
}
```

Έχετε επίσης μεθόδους για την ανάγνωση και την εγγραφή των περιεχομένων ενός αρχείου:

```php
foreach ($finder as $file) {
    $contents = $file->read();
    // ...
    $file->write($contents);
}
```


Επιστροφή αποτελεσμάτων ως συστοιχία .[#toc-returning-results-as-an-array]
--------------------------------------------------------------------------

Όπως είδαμε στα παραδείγματα, το Finder υλοποιεί τη διεπαφή `IteratorAggregate`, οπότε μπορείτε να χρησιμοποιήσετε το `foreach` για να περιηγηθείτε στα αποτελέσματα. Είναι προγραμματισμένο έτσι ώστε τα αποτελέσματα να φορτώνονται μόνο κατά την περιήγησή σας, οπότε αν έχετε μεγάλο αριθμό αρχείων, δεν περιμένει να διαβαστούν όλα.

Μπορείτε επίσης να επιστρέψετε τα αποτελέσματα ως πίνακα αντικειμένων `Nette\Utils\FileInfo`, χρησιμοποιώντας τη μέθοδο `collect()`. Ο πίνακας δεν είναι συσχετιστικός, αλλά αριθμητικός.

```php
$array = $finder->findFiles('*.php')->collect();
```