README

Documentation complète de la classe Npds\Filesystem\FileFinder pour la recherche et le filtrage avancé de fichiers.

Installation et initialisation

use Npds\Filesystem\FileFinder;

// Créer une nouvelle instance
$finder = FileFinder::create();

Création d'instance

1. create()

Crée une nouvelle instance de FileFinder prête à être configurée.

$finder = FileFinder::create();

Configuration des chemins

2. in()

Définit les chemins de recherche. Accepte un chemin unique ou un tableau de chemins.

// Chemin unique
$finder->in('/mon/dossier');

// Plusieurs chemins
$finder->in(['/dossier1', '/dossier2']);

Filtres de type

3. files()

Recherche uniquement les fichiers, excluant les dossiers.

$finder->files();

4. directories()

Recherche uniquement les dossiers, excluant les fichiers.

$finder->directories();

5. all()

Recherche à la fois les fichiers et les dossiers (comportement par défaut).

$finder->all();

Filtres de profondeur

6. depth()

Limite la profondeur de recherche dans l'arborescence des dossiers.

// Maximum 3 niveaux
$finder->depth(3);

// Exactement 2 niveaux
$finder->depth('== 2');

// Plus de 1 niveau
$finder->depth('> 1');

// 4 niveaux ou moins
$finder->depth('<= 4');

Filtres par nom

7. name()

Filtre les fichiers par nom en utilisant des patterns (caractères génériques).

// Tous les fichiers PHP
$finder->name('*.php');

// Plusieurs extensions
$finder->name('*.{php,html,js}');

// Tableau de patterns
$finder->name(['*.txt', '*.md']);

8. notName()

Exclut les fichiers correspondant à un pattern.

// Exclure les fichiers temporaires
$finder->notName('*.tmp');

// Exclure plusieurs patterns
$finder->notName(['*.log', '*.cache']);

9. extensions()

Filtre par extension de fichier (méthode pratique).

// Images seulement
$finder->extensions(['jpg', 'png', 'gif']);

// PHP seulement
$finder->extensions('php');

Filtres de contenu

10. contains()

Recherche les fichiers contenant un texte spécifique.

// Fichiers contenant "class User"
$finder->contains('class User');

// Fichiers avec des TODOs
$finder->contains('TODO:');

11. notContains()

Exclut les fichiers contenant un texte spécifique.

// Exclure fichiers avec "password"
$finder->notContains('password');

// Exclure fichiers avec "secret"
$finder->notContains('secret');

Filtres d'état

12. empty()

Filtre les fichiers vides ou non vides.

// Fichiers vides seulement
$finder->empty(true);

// Fichiers non vides seulement
$finder->empty(false);

Filtres de visibilité

13. ignoreDotFiles()

Ignore ou inclut les fichiers cachés (commençant par un point).

// Ignorer les fichiers cachés
$finder->ignoreDotFiles(true);

// Inclure les fichiers cachés
$finder->ignoreDotFiles(false);

Exclusions

14. exclude()

Exclut complètement des dossiers de la recherche.

// Exclure un dossier
$finder->exclude('node_modules');

// Exclure plusieurs dossiers
$finder->exclude(['vendor', 'cache', 'logs']);

15. notPath()

Exclut par chemin en utilisant des patterns.

// Exclure tout dans les dossiers tests
$finder->notPath('*/tests/*');

// Exclure les fichiers minifiés
$finder->notPath('*.min.js');

Filtres personnalisés

16. filter()

Applique un filtre personnalisé via une fonction callback.

// Exclure les fichiers de plus de 10 Mo
$finder->filter(function($file, $iterator) {
    return $file->getSize() <= 10 * 1024 * 1024;
});

Tri des résultats

17. sortByName()

Trie les résultats par nom de fichier.

// Ordre ascendant (A à Z)
$finder->sortByName();

// Ordre descendant (Z à A)
$finder->sortByName(true);

18. sortByModified()

Trie les résultats par date de modification.

// Plus anciens d'abord
$finder->sortByModified();

// Plus récents d'abord
$finder->sortByModified(true);

19. sortBySize()

Trie les résultats par taille de fichier.

// Plus petits d'abord
$finder->sortBySize();

// Plus grands d'abord
$finder->sortBySize(true);

20. sortByType()

Trie par type (dossiers puis fichiers, ou l'inverse).

// Dossiers d'abord, puis fichiers
$finder->sortByType();

// Fichiers d'abord, puis dossiers
$finder->sortByType(true);

21. sort()

Tri personnalisé avec une fonction de comparaison.

// Trier par date de création
$finder->sort(function($a, $b) {
    return $a->getCTime() <=> $b->getCTime();
});

Filtres temporels

22. date()

Filtre par date de modification du fichier.

// Modifiés après le 1er janvier 2024
$finder->date('>= 2024-01-01');

// Modifiés avant 2024
$finder->date('<= 2023-12-31');

// Modifiés dans les 7 derniers jours
$finder->date('> now - 7 days');

// Modifiés exactement le 15 juin 2024
$finder->date('= 2024-06-15');

Filtres de taille

23. size()

Filtre par taille de fichier.

// Plus de 1 Mo
$finder->size('> 1M');

// 100 Ko ou moins
$finder->size('<= 100K');

// Exactement 500 Ko
$finder->size('500K');

// Entre 1 Ko et 1 Mo
$finder->size(['> 1K', '< 1M']);

Options système

24. followLinks()

Active ou désactive le suivi des liens symboliques.

// Suivre les liens symboliques
$finder->followLinks(true);

25. ignoreVCS()

Ignore les répertoires de contrôle de version (.git, .svn, etc.).

// Ignorer les répertoires VCS
$finder->ignoreVCS(true);

26. addVCSPattern()

Ajoute un pattern VCS personnalisé à ignorer.

// Ignorer aussi le dossier .myvcs
$finder->addVCSPattern('.myvcs');

27. ignoreVCSIgnored()

Respecte les règles définies dans .gitignore.

// Respecter le fichier .gitignore
$finder->ignoreVCSIgnored(true);

28. ignoreUnreadableDirs()

Contrôle le comportement face aux dossiers non lisibles.

// Lancer une exception si dossier non lisible
$finder->ignoreUnreadableDirs(false);

Récupération des résultats

29. get()

Récupère tous les résultats sous forme de tableau d'objets SplFileInfo.

$resultats = $finder->get(); // Tableau de SplFileInfo

30. getPaths()

Récupère uniquement les chemins complets des fichiers trouvés.

$chemins = $finder->getPaths(); // Tableau de chemins

31. getNames()

Récupère uniquement les noms de fichiers.

$noms = $finder->getNames(); // Tableau de noms

32. getContents()

Récupère les contenus de tous les fichiers trouvés.

$contenus = $finder->getContents(); // Tableau [chemin => contenu]

33. first()

Retourne le premier résultat trouvé.

$premier = $finder->first(); // SplFileInfo ou null

34. last()

Retourne le dernier résultat trouvé.

$dernier = $finder->last(); // SplFileInfo ou null

Interfaces natives PHP

35. getIterator()

Utilise le finder comme itérateur dans une boucle foreach.

foreach ($finder as $fichier) {
    echo $fichier->getPathname() . "\n";
}

36. count()

Retourne le nombre de résultats trouvés.

$nombre = count($finder);
// Ou
$nombre = $finder->count();

37. hasResults()

Vérifie s'il y a au moins un résultat.

if ($finder->hasResults()) {
    echo "Des fichiers ont été trouvés";
}

Exemples complets

Exemple 1 : Recherche de fichiers PHP modifiés récemment

$fichiersPHP = FileFinder::create()
    ->in('/var/www/projet')
    ->files()
    ->extensions(['php'])
    ->date('> now - 7 days')
    ->sortByModified(true)
    ->get();

foreach ($fichiersPHP as $fichier) {
    echo "Modifié récemment: " . $fichier->getPathname() . "\n";
}

Exemple 2 : Recherche de fichiers images volumineux

$imagesVolumineuses = FileFinder::create()
    ->in('/home/user/images')
    ->files()
    ->extensions(['jpg', 'jpeg', 'png', 'gif'])
    ->size('> 5M')
    ->sortBySize(true)
    ->getPaths();

echo "Images de plus de 5Mo: " . implode(', ', $imagesVolumineuses);

Exemple 3 : Nettoyage de fichiers temporaires

$fichiersTmp = FileFinder::create()
    ->in('/tmp')
    ->files()
    ->name('*.tmp')
    ->date('< now - 30 days')
    ->get();

foreach ($fichiersTmp as $fichier) {
    unlink($fichier->getPathname());
    echo "Supprimé: " . $fichier->getPathname() . "\n";
}

Exemple 4 : Analyse de logs d'erreurs

$logsErreurs = FileFinder::create()
    ->in('/var/log')
    ->files()
    ->name('*.log')
    ->contains('ERROR')
    ->notContains('DEBUG')
    ->getContents();

foreach ($logsErreurs as $chemin => $contenu) {
    echo "Fichier: $chemin contient des erreurs\n";
}

Exemple 5 : Recherche dans un projet en ignorant les dépendances

$fichiersProjet = FileFinder::create()
    ->in('/mon/projet')
    ->files()
    ->notPath('*/node_modules/*')
    ->notPath('*/vendor/*')
    ->notName('*.min.js')
    ->notName('*.min.css')
    ->filter(function($file, $iterator) {
        // Exclure les fichiers de plus de 1 Mo
        return $file->getSize() < 1024 * 1024;
    })
    ->sortByName()
    ->get();

Exemple 6 : Sauvegarde de fichiers importants

$fichiersImportants = FileFinder::create()
    ->in('/documents')
    ->files()
    ->extensions(['docx', 'xlsx', 'pdf'])
    ->date('>= 2024-01-01')
    ->size('> 10K')
    ->get();

$backupDir = '/backup/' . date('Y-m-d');
if (!is_dir($backupDir)) {
    mkdir($backupDir, 0755, true);
}

foreach ($fichiersImportants as $fichier) {
    copy($fichier->getPathname(), $backupDir . '/' . $fichier->getFilename());
}

Exemple 7 : Utilisation avec Filesystem

use Npds\Filesystem\Filesystem;

$fs = new Filesystem();
$finder = $fs->find('/mon/dossier') // Retourne un FileFinder configuré
    ->files()
    ->extensions(['php'])
    ->contains('namespace');

foreach ($finder as $fichier) {
    echo $fichier->getPathname() . "\n";
}

Exemple 8 : Chaînage conditionnel

$chemin = '/some/path';
$finder = FileFinder::create()->in($chemin)->files();

if ($rechercheImages) {
    $finder->extensions(['jpg', 'png']);
}

if ($recentOnly) {
    $finder->date('>= now - 7 days');
}

$resultats = $finder->get();

Exemple 9 : Recherche récursive avec limites

$finder = FileFinder::create()
    ->in('/home/user')
    ->depth(5) // Maximum 5 niveaux
    ->ignoreDotFiles(true)
    ->ignoreVCS(true)
    ->files()
    ->name('*.conf')
    ->size('<= 100K')
    ->getPaths();

Exemple 10 : Comptage et vérification

$finder = FileFinder::create()
    ->in('/tmp')
    ->files()
    ->name('*.cache');

if ($finder->hasResults()) {
    echo "Nombre de fichiers cache: " . $finder->count() . "\n";
    
    foreach ($finder as $cache) {
        echo "Cache: " . $cache->getPathname() . "\n";
    }
}

Exemple 11 : Recherche de doublons par taille et nom

$fichiersParTaille = [];
$finder = FileFinder::create()
    ->in('/downloads')
    ->files()
    ->sortBySize();

foreach ($finder as $fichier) {
    $cle = $fichier->getSize() . '_' . $fichier->getFilename();
    if (isset($fichiersParTaille[$cle])) {
        echo "Doublon potentiel: " . $fichier->getPathname() . "\n";
    } else {
        $fichiersParTaille[$cle] = $fichier->getPathname();
    }
}

Exemple 12 : Extraction d'informations et statistiques

$finder = FileFinder::create()
    ->in('/var/www')
    ->files()
    ->extensions(['php', 'html', 'js'])
    ->date('>= 2024-01-01');

$stats = [
    'total' => 0,
    'taille_totale' => 0,
    'par_extension' => []
];

foreach ($finder as $fichier) {
    $stats['total']++;
    $stats['taille_totale'] += $fichier->getSize();
    
    $ext = pathinfo($fichier->getFilename(), PATHINFO_EXTENSION);
    $stats['par_extension'][$ext] = ($stats['par_extension'][$ext] ?? 0) + 1;
}

print_r($stats);

Cas d'utilisation avancés

1. Recherche de fichiers sensibles

$fichiersSensibles = FileFinder::create()
    ->in('/home/user')
    ->files()
    ->name(['*.env', 'config*.php', '*.pem', '*.key'])
    ->ignoreVCS(true)
    ->get();

foreach ($fichiersSensibles as $fichier) {
    echo "Fichier sensible trouvé: " . $fichier->getPathname() . "\n";
}

2. Organisation de médias

$medias = FileFinder::create()
    ->in('/téléchargements')
    ->files()
    ->extensions(['mp3', 'mp4', 'avi', 'mkv', 'jpg', 'png'])
    ->sortByType() // Dossiers d'abord
    ->sortByName() // Puis par nom
    ->get();

foreach ($medias as $media) {
    $type = $media->isDir() ? 'Dossier' : 'Fichier';
    echo "$type: " . $media->getFilename() . "\n";
}

3. Analyse de projet

$analyseProjet = function($dossier) {
    $finder = FileFinder::create()->in($dossier);
    
    return [
        'fichiers' => $finder->files()->count(),
        'dossiers' => $finder->directories()->count(),
        'php' => $finder->files()->extensions(['php'])->count(),
        'js' => $finder->files()->extensions(['js'])->count(),
        'css' => $finder->files()->extensions(['css'])->count(),
        'tests' => $finder->files()->name('*Test.php')->count(),
    ];
};

print_r($analyseProjet('/mon/projet'));

4. Sauvegarde incrémentielle

$derniereSauvegarde = strtotime('yesterday');
$fichiersModifies = FileFinder::create()
    ->in('/data')
    ->files()
    ->date('> ' . date('Y-m-d H:i:s', $derniereSauvegarde))
    ->get();

foreach ($fichiersModifies as $fichier) {
    // Copier seulement les fichiers modifiés depuis la dernière sauvegarde
    copy($fichier->getPathname(), '/backup/' . $fichier->getFilename());
}

5. Recherche de fichiers corrompus

$fichiersVides = FileFinder::create()
    ->in('/storage')
    ->files()
    ->empty(true)
    ->size('0')
    ->get();

foreach ($fichiersVides as $fichier) {
    echo "Fichier vide ou corrompu: " . $fichier->getPathname() . "\n";
    // Option: $fs->delete($fichier->getPathname());
}

Conseils et bonnes pratiques

Chaînage de méthodes : FileFinder supporte le chaînage fluent pour une syntaxe élégante
Filtres combinés : Combinez plusieurs filtres pour affiner votre recherche
Performance : Utilisez exclude() et notPath() pour réduire l'espace de recherche
Tri multiple : Vous pouvez chaîner plusieurs méthodes de tri
Résultats : Choisissez la méthode de récupération appropriée (get(), getPaths(), etc.)
Itération : Vous pouvez itérer directement sur un FileFinder avec foreach
VCS : Utilisez ignoreVCS() pour ignorer automatiquement les répertoires de versioning
Gros volumes : Pour d'énormes résultats, utilisez l'itération plutôt que get()

nicolas2-dev / npds-filefinder

Maintainers

Details