README

Documentation complète de la classe Npds\Filesystem\Filesystem pour la gestion des fichiers et dossiers en PHP.

Installation et initialisation

use Npds\Filesystem\Filesystem;

$fs = new Filesystem();

Constructeur et recherche

1. Constructeur

Crée une instance de la classe Filesystem pour accéder à tous les services de gestion de fichiers.

$fs = new Filesystem();

2. find()

Crée un FileFinder configuré pour chercher des fichiers avec des critères personnalisés.

$finder = $fs->find('/mon/dossier');

// Avec plusieurs chemins
$finder = $fs->find(['/dossier1', '/dossier2']);

Listage et recherche

3. files()

Liste les fichiers d'un dossier sans récursivité.

$fichiers = $fs->files('/mon/dossier');

// Inclure les fichiers cachés
$fichiersAvecCaches = $fs->files('/mon/dossier', true);

4. allFiles()

Liste tous les fichiers de manière récursive dans un dossier et ses sous-dossiers.

$tousFichiers = $fs->allFiles('/mon/projet');

// Avec fichiers cachés
$tousAvecCaches = $fs->allFiles('/mon/projet', true);

5. directories()

Liste les dossiers d'un répertoire sans récursivité.

$dossiers = $fs->directories('/mon/dossier');

6. allDirectories()

Liste tous les dossiers de manière récursive.

$tousDossiers = $fs->allDirectories('/mon/projet');

7. findFiles()

Recherche de fichiers avec des critères avancés.

$fichiersPHP = $fs->findFiles('/src', [
    'extensions' => ['php'],
    'contains' => 'class',
    'sortByName' => true
]);

8. findDirectories()

Recherche de dossiers avec des critères spécifiques.

$dossiersRecents = $fs->findDirectories('/backup', [
    'date' => '>= 2024-01-01',
    'sortByModified' => true
]);

9. glob()

Recherche par motif utilisant la syntaxe glob standard.

$fichiersConf = $fs->glob('/etc/*.conf');

// Uniquement les dossiers
$dossiersSeuls = $fs->glob('/var/*', GLOB_ONLYDIR);

10. globRecursive()

Recherche récursive par motif.

$tousFichiersLog = $fs->globRecursive('/var/log/*.log');

11. findPaths()

Recherche et retourne les chemins complets des fichiers correspondants.

$cheminsImages = $fs->findPaths('/uploads', [
    'extensions' => ['jpg', 'png', 'gif'],
    'size' => '> 100K'
]);

12. findNames()

Recherche et retourne uniquement les noms des fichiers.

$nomsLogs = $fs->findNames('/logs', [
    'name' => '*.log',
    'sortByModified' => true
]);

Opérations sur fichiers

13. exists()

Vérifie si un chemin (fichier ou dossier) existe.

if ($fs->exists('/chemin/fichier.txt')) {
    echo "Le fichier existe";
}

14. get()

Lit et retourne le contenu complet d'un fichier.

$contenu = $fs->get('/fichier.txt');

// Lecture avec verrou exclusif
$contenuVerrouille = $fs->get('/fichier.txt', true);

15. put()

Écrit du contenu dans un fichier (crée le fichier s'il n'existe pas, sinon le remplace).

$succes = $fs->put('/nouveau.txt', 'Contenu du fichier');

// Écriture avec verrou exclusif
$succesVerrou = $fs->put('/important.txt', 'Données critiques', true);

16. append()

Ajoute du contenu à la fin d'un fichier existant.

$fs->append('/log.txt', "Nouvelle entrée\n");

17. prepend()

Ajoute du contenu au début d'un fichier.

$fs->prepend('/config.php', "<?php\n// Fichier généré\n");

18. delete()

Supprime un ou plusieurs fichiers.

// Supprimer un fichier
$fs->delete('/fichier.txt');

// Supprimer plusieurs fichiers
$fs->delete(['/fichier1.txt', '/fichier2.txt']);

19. move()

Déplace un fichier d'un emplacement à un autre.

$fs->move('/ancien.txt', '/nouveau.txt');

20. copy()

Copie un fichier vers une nouvelle destination.

$fs->copy('/original.jpg', '/backup.jpg');

21. link()

Crée un lien symbolique vers un fichier.

$fs->link('/target/file', '/link/to/file');

22. lines()

Lit un fichier ligne par ligne en utilisant un générateur (idéal pour les gros fichiers).

foreach ($fs->lines('/fichier.csv') as $ligne) {
    echo $ligne . "\n";
}

Informations sur fichiers

23. mimeType()

Obtient le type MIME d'un fichier.

$type = $fs->mimeType('/image.jpg');
// Retourne: 'image/jpeg'

24. size()

Obtient la taille d'un fichier en octets.

$taille = $fs->size('/archive.zip');

25. lastModified()

Obtient le timestamp de la dernière modification.

$timestamp = $fs->lastModified('/fichier.txt');
$date = date('Y-m-d H:i:s', $timestamp);

26. isFile()

Vérifie si le chemin pointe vers un fichier.

if ($fs->isFile('/chemin')) {
    echo "C'est un fichier";
}

27. isDirectory()

Vérifie si le chemin pointe vers un dossier.

if ($fs->isDirectory('/chemin')) {
    echo "C'est un dossier";
}

28. isReadable()

Vérifie si un fichier est lisible.

if ($fs->isReadable('/fichier.txt')) {
    echo "Fichier lisible";
}

29. isWritable()

Vérifie si un fichier est inscriptible.

if ($fs->isWritable('/fichier.txt')) {
    echo "Fichier inscriptible";
}

Opérations sur dossiers

30. makeDirectory()

Crée un ou plusieurs dossiers.

// Créer un dossier simple
$fs->makeDirectory('/nouveau/dossier', 0755);

// Créer récursivement (avec tous les parents)
$fs->makeDirectory('/nouveau/dossier/profond', 0755, true);

31. moveDirectory()

Déplace un dossier entier avec tout son contenu.

// Déplacer et écraser si la destination existe
$fs->moveDirectory('/ancien', '/nouveau', true);

32. copyDirectory()

Copie un dossier et tout son contenu de manière récursive.

$fs->copyDirectory('/source', '/destination');

33. deleteDirectory()

Supprime un dossier et tout son contenu de manière récursive.

$fs->deleteDirectory('/dossier/supprimer');

34. cleanDirectory()

Vide complètement un dossier en supprimant tout son contenu.

$fs->cleanDirectory('/tmp/cache');

35. ensureDirectoryExists()

S'assure qu'un dossier existe, le crée s'il n'existe pas.

$fs->ensureDirectoryExists('/chemin/vers/dossier');

Informations chemin

36. extension()

Obtient l'extension d'un fichier.

$ext = $fs->extension('/fichier.txt');
// Retourne: 'txt'

37. name()

Obtient le nom du fichier sans extension.

$nom = $fs->name('/fichier.txt');
// Retourne: 'fichier'

38. basename()

Obtient le nom du fichier avec extension.

$basename = $fs->basename('/chemin/fichier.txt');
// Retourne: 'fichier.txt'

39. dirname()

Obtient le chemin du dossier parent.

$parent = $fs->dirname('/chemin/vers/fichier.txt');
// Retourne: '/chemin/vers'

40. type()

Retourne le type de l'élément : 'file', 'dir', ou 'link'.

$type = $fs->type('/chemin');
// Retourne: 'file', 'dir', ou 'link'

Permissions et propriété

41. chmod()

Change les permissions d'un fichier.

$fs->chmod('/script.sh', 0755);

42. chown()

Change le propriétaire d'un fichier ou dossier.

// Changer le propriétaire
$fs->chown('/fichier', 'www-data');

// Changer le propriétaire récursivement
$fs->chown('/dossier', 'www-data', true);

43. chgrp()

Change le groupe d'un fichier ou dossier.

// Changer le groupe
$fs->chgrp('/fichier', 'www-data');

// Changer le groupe récursivement
$fs->chgrp('/dossier', 'www-data', true);

Autres opérations

44. rename()

Renomme un fichier ou dossier.

$fs->rename('/ancien.txt', '/nouveau.txt');

45. json()

Lit un fichier JSON et le retourne en tant que tableau PHP.

$config = $fs->json('/config.json', true);
// Retourne un tableau PHP

46. putJson()

Écrit des données PHP en tant que fichier JSON.

$data = ['nom' => 'test', 'valeur' => 123];
$fs->putJson('/data.json', $data);

47. getRequire()

Inclut un fichier PHP et retourne son résultat.

$config = $fs->getRequire('/config.php');

48. getRequireOnce()

Inclut un fichier PHP une seule fois et retourne son résultat.

$fonctions = $fs->getRequireOnce('/functions.php');

49. replace()

Écrit un contenu de manière atomique (remplace le fichier de façon sécurisée).

$fs->replace('/config.php', '<?php return [];');

50. relativePath()

Calcule le chemin relatif entre deux chemins.

$relatif = $fs->relativePath('/var/www', '/var/www/public/index.php');
// Retourne: 'public/index.php'

51. touch()

Met à jour la date d'accès et de modification d'un fichier.

// Met à jour à l'heure actuelle
$fs->touch('/fichier.txt');

// Met à jour à un timestamp spécifique
$fs->touch('/fichier.txt', time() - 3600);
// Il y a une heure

52. readlink()

Lit la cible d'un lien symbolique.

$cible = $fs->readlink('/lien');

53. stat()

Obtient les informations système détaillées d'un fichier.

$infos = $fs->stat('/fichier.txt');
// Tableau avec: size, atime, mtime, ctime, etc.

54. isLink()

Vérifie si le chemin pointe vers un lien symbolique.

if ($fs->isLink('/lien')) {
    echo "C'est un lien symbolique";
}

55. fileInfo()

Retourne un objet SplFileInfo avec toutes les informations du fichier.

$info = $fs->fileInfo('/fichier.txt');
echo $info->getSize();
echo $info->getMTime();

Méthodes protégées et internes

Ces méthodes sont utilisées en interne par la classe et ne doivent généralement pas être appelées directement.

56. sharedGet()

Lecture avec verrou partagé (utilisée en interne par get()).

57. putWithLock()

Écriture avec verrou exclusif (utilisée en interne par put()).

58. guessMimeTypeByExtension()

Devine le type MIME en fonction de l'extension du fichier (utilisée en interne par mimeType()).

Exemples complets

Exemple 1 : Backup d'un dossier

function backupDossier(Filesystem $fs, string $source, string $destination) {
    if (!$fs->exists($destination)) {
        $fs->makeDirectory($destination, 0755, true);
    }
    
    $fs->copyDirectory($source, $destination);
    echo "Backup terminé: " . count($fs->allFiles($destination)) . " fichiers copiés";
}

Exemple 2 : Nettoyage de fichiers temporaires

function nettoyerTemporaires(Filesystem $fs, string $dossier, int $jours) {
    $limite = time() - ($jours * 86400);
    
    $fichiers = $fs->findFiles($dossier, [
        'date' => '< ' . date('Y-m-d', $limite),
        'name' => '*.tmp'
    ]);
    
    foreach ($fichiers as $fichier) {
        $fs->delete($fichier->getPathname());
    }
    
    echo count($fichiers) . " fichiers nettoyés";
}

Exemple 3 : Recherche de fichiers contenant du texte

function rechercherDansFichiers(Filesystem $fs, string $dossier, string $texte) {
    $resultats = $fs->findFiles($dossier, [
        'contains' => $texte,
        'extensions' => ['php', 'txt', 'html']
    ]);
    
    foreach ($resultats as $fichier) {
        echo "Trouvé dans: " . $fichier->getPathname() . "\n";
    }
}

Exemple 4 : Synchronisation de deux dossiers

function synchroniserDossiers(Filesystem $fs, string $source, string $cible) {
    // Nettoyer la cible
    $fs->cleanDirectory($cible);
    
    // Copier tous les fichiers
    $fichiers = $fs->allFiles($source);
    
    foreach ($fichiers as $fichier) {
        $cheminRelatif = $fs->relativePath($source, $fichier->getPathname());
        $cibleChemin = $cible . '/' . $cheminRelatif;
        
        $fs->ensureDirectoryExists(dirname($cibleChemin));
        $fs->copy($fichier->getPathname(), $cibleChemin);
    }
    
    echo "Synchronisation terminée";
}

Exemple 5 : Analyse d'un dossier

function analyserDossier(Filesystem $fs, string $dossier) {
    $stats = [
        'total_fichiers' => count($fs->allFiles($dossier)),
        'total_dossiers' => count($fs->allDirectories($dossier)),
        'taille_totale' => 0,
        'extensions' => [],
        'fichiers_recents' => []
    ];
    
    foreach ($fs->allFiles($dossier) as $fichier) {
        // Taille totale
        $stats['taille_totale'] += $fs->size($fichier->getPathname());
        
        // Extensions
        $ext = $fs->extension($fichier->getPathname());
        $stats['extensions'][$ext] = ($stats['extensions'][$ext] ?? 0) + 1;
        
        // Fichiers récents (moins de 7 jours)
        if ($fs->lastModified($fichier->getPathname()) > time() - 604800) {
            $stats['fichiers_recents'][] = $fichier->getPathname();
        }
    }
    
    return $stats;
}

Cas d'utilisation courants

1. Logging

$fs->append('/var/log/app.log', date('Y-m-d H:i:s') . " - Action effectuée\n");

2. Configuration

$config = $fs->json('/etc/app/config.json') ?? [];
$config['dernier_acces'] = time();
$fs->putJson('/etc/app/config.json', $config);

3. Upload de fichiers

$uploadDir = '/uploads/' . date('Y-m');
$fs->ensureDirectoryExists($uploadDir);
$fs->move('/tmp/upload.jpg', $uploadDir . '/image.jpg');

4. Gestion du cache

$cacheFile = '/cache/' . md5($key) . '.cache';

// Vérifier si le cache est valide (moins de 1 heure)
if ($fs->exists($cacheFile) && $fs->lastModified($cacheFile) > time() - 3600) {
    return $fs->get($cacheFile);
}

// Sinon, créer le cache
$fs->put($cacheFile, $donnees);

5. Traitement de templates

$template = $fs->get('/templates/base.html');
$content = str_replace('{{title}}', $titre, $template);
$fs->put('/output/page.html', $content);

Conseils d'utilisation

Utilisez les méthodes append() et prepend() pour ajouter du contenu sans remplacer le fichier entier
Préférez lines() pour lire de gros fichiers afin de ne pas charger toute la mémoire
Utilisez relativePath() pour créer des chemins portables
Toujours vérifier l'existence et les permissions avant d'opérer sur des fichiers critiques
Utilisez ensureDirectoryExists() avant de créer des fichiers dans un dossier qui pourrait ne pas exister
Profitez des options de verrou pour les opérations critiques sur des fichiers utilisés par plusieurs processus

nicolas2-dev / npds-filesystem

Maintainers

Details