Folder & File

Les utilitaires Folder et File sont des classes pratiques pour la lecture, l’écriture/l’ajout de fichiers, lister les fichiers d’un dossier et toute autre tâche habituelle liée aux répertoires.

Obsolète depuis la version 4.0: Les classes File et Folder vont être retirées dans la version 5.0. Utilisez plutôt les classes SplFileInfo ou SplFileObject et les classes d’itérateurs comme RecursiveDirectoryIterator, RecursiveRegexIterator etc.

Utilisation Basique

Assurez-vous que les classes sont chargées:

use Cake\Filesystem\Folder;
use Cake\Filesystem\File;

Ensuite nous pouvons configurer une nouvelle instance de dossier:

$dir = new Folder('/path/to/folder');

et chercher tous les fichiers .php à l’intérieur de ce dossier en utilisant les regex:

$files = $dir->find('.*\.php');

Maintenant nous pouvons faire une boucle sur les fichiers et les lire, écrire/ajouter aux contenus, ou simplement supprimer le fichier:

foreach ($files as $file) {
    $file = new File($dir->pwd() . DS . $file);
    $contents = $file->read();
    // $file->write('J'écris dans ce fichier');
    // $file->append('J'ajoute à la fin de ce fichier.');
    // $file->delete(); // Je supprime ce fichier
    $file->close(); // Assurez-vous de fermer le fichier quand c'est fini
}

API de Folder

class Cake\Filesystem\Folder(string $path = false, boolean $create = false, string|boolean $mode = false)
// Crée un nouveau dossier avec les permissions à 0755
$dir = new Folder('/path/to/folder', true, 0755);
property Cake\Filesystem\Folder::$path

Le chemin pour le dossier courant. Folder::pwd() retournera la même information.

property Cake\Filesystem\Folder::$sort

Dit si la liste des résultats doit être oui ou non rangée par ordre alphabétique.

property Cake\Filesystem\Folder::$mode

Mode à utiliser pour la création de dossiers. par défaut à 0755. Ne fait rien sur les machines Windows.

static Cake\Filesystem\Folder::addPathElement(string $path, string $element)

Retourne $path avec $element ajouté, avec le bon slash entre-deux:

$path = Folder::addPathElement('/un/chemin/pour', 'tester');
// $path égal /un/chemin/pour/tester

$element peut aussi être un tableau:

$path = Folder::addPathElement('/un/chemin/pour', ['un-autre', 'test']);
// $path égal à /un/chemin/pour/un-autre/test
Cake\Filesystem\Folder::cd($path)

Change le répertoire en $path. Retourne false en cas d’échec:

$folder = new Folder('/foo');
echo $folder->path; // Affiche /foo
$folder->cd('/bar');
echo $folder->path; // Affiche /bar
$false = $folder->cd('/repertoire-inexistant');
Cake\Filesystem\Folder::chmod(string $path, integer $mode = false, boolean $recursive = true, array $exceptions = [])

Change le mode sur la structure de répertoire de façon récursive. Ceci inclut aussi le changement du mode des fichiers:

$dir = new Folder();
$dir->chmod('/path/to/folder', 0755, true, ['skip_me.php']);
Cake\Filesystem\Folder::copy(array|string $options = [])

Copie de façon récursive un répertoire. Le seul paramètre $options peut être soit un chemin à copier soit un tableau d’options:

$folder1 = new Folder('/path/to/folder1');
$folder1->copy('/path/to/folder2');
// mettra le folder1 et tout son contenu dans folder2

$folder = new Folder('chemin/vers/repertoire');
$folder->copy([
    'to' => '/chemin/vers/nouveau/repertoire',
    'from' => '/chemin/de/depart', // Va provoquer un cd()
    'mode' => 0755,
    'skip' => ['bon-a-ignorer.php', '.git'],
    'scheme' => Folder::SKIP  // Ne crée pas les répertoires/fichiers qui existent déjà.
]);

Il y a 3 schémas supportés:

  • Folder::SKIP échapper la copie/déplacement des fichiers & répertoires qui existent dans le répertoire de destination.

  • Folder::MERGE fusionne les répertoires source/destination. Les fichiers dans le répertoire source vont remplacer les fichiers dans le répertoire de cible. Les contenus du répertoire seront fusionnés.

  • Folder::OVERWRITE écrase les fichiers & répertoires existant dans le répertoire cible avec ceux dans le répertoire source. Si la source et la destination contiennent le même sous-répertoire, les contenus du répertoire de cible vont être retirés et remplacés avec celui de la source.

static Cake\Filesystem\Folder::correctSlashFor(string $path)

Retourne un ensemble correct de slashes pour un $path donné. (”\” pour les chemins Windows et “/” pour les autres chemins).

Cake\Filesystem\Folder::create(string $pathname, integer $mode = false)

Crée une structure de répertoire de façon récursive. Peut être utilisée pour créer des structures de chemin profond comme /foo/bar/baz/shoe/horn:

$folder = new Folder();
if ($folder->create('foo' . DS . 'bar' . DS . 'baz' . DS . 'shoe' . DS . 'horn')) {
    // Répertoires imbriqués créés avec succèse
}
Cake\Filesystem\Folder::delete(string $path = null)

Efface de façon récursive les répertoires si le système le permet:

$folder = new Folder('foo');
if ($folder->delete()) {
    // Supprime foo et ses dossiers imbriqués avec succès
}
Cake\Filesystem\Folder::dirsize()

Retourne la taille en octets de ce dossier et ses contenus.

Cake\Filesystem\Folder::errors()

Récupère l’erreur de la dernière méthode.

Cake\Filesystem\Folder::find(string $regexpPattern = '.*', boolean $sort = false)

Retourne un tableau de tous les fichiers correspondants dans le répertoire courant:

// Trouve tous les .png dans votre dossier webroot/img/ et range les résultats
$dir = new Folder(WWW_ROOT . 'img');
$files = $dir->find('.*\.png', true);
/*
Array
(
    [0] => cake.icon.png
    [1] => test-error-icon.png
    [2] => test-fail-icon.png
    [3] => test-pass-icon.png
    [4] => test-skip-icon.png
)
*/

Note

Les méthodes find et findRecursive de folder ne trouvent seulement que des fichiers. Si vous voulez obtenir des dossiers et fichiers, regardez Folder::read() ou Folder::tree().

Cake\Filesystem\Folder::findRecursive(string $pattern = '.*', boolean $sort = false)

Retourne un tableau de tous les fichiers correspondants dans et en-dessous du répertoire courant:

// Trouve de façon récursive les fichiers commençant par test ou index
$dir = new Folder(WWW_ROOT);
$files = $dir->findRecursive('(test|index).*');
/*
Array
(
    [0] => /var/www/cake/webroot/index.php
    [1] => /var/www/cake/webroot/test.php
    [2] => /var/www/cake/webroot/img/test-skip-icon.png
    [3] => /var/www/cake/webroot/img/test-fail-icon.png
    [4] => /var/www/cake/webroot/img/test-error-icon.png
    [5] => /var/www/cake/webroot/img/test-pass-icon.png
)
*/
Cake\Filesystem\Folder::inCakePath(string $path = '')

Retourne true si le fichier est dans un CakePath donné.

Cake\Filesystem\Folder::inPath(string $path = '', boolean $reverse = false)

Retourne true si le fichier est dans le chemin donné:

$Folder = new Folder(WWW_ROOT);
$result = $Folder->inPath(APP);
// $result = true, /var/www/example/ est dans /var/www/example/webroot/

$result = $Folder->inPath(WWW_ROOT . 'img' . DS, true);
// $result = true, /var/www/example/webroot/ est dans /var/www/example/webroot/img/
static Cake\Filesystem\Folder::isAbsolute(string $path)

Retourne true si le $path donné est un chemin absolu.

static Cake\Filesystem\Folder::isSlashTerm(string $path)

Retourne true si le $path donné finit par un slash (par exemple. se termine-par-un-slash):

$result = Folder::isSlashTerm('/my/test/path');
// $result = false
$result = Folder::isSlashTerm('/my/test/path/');
// $result = true
static Cake\Filesystem\Folder::isWindowsPath(string $path)

Retourne true si le $path donné est un chemin Windows.

Cake\Filesystem\Folder::messages()

Récupère les messages de la dernière méthode.

Cake\Filesystem\Folder::move(array $options)

Déplace le répertoire de façon récursive.

static Cake\Filesystem\Folder::normalizeFullPath(string $path)

Retourne un chemin avec des slashes normalisés pour le système d’exploitation.

Cake\Filesystem\Folder::pwd()

Retourne le chemin courant.

Cake\Filesystem\Folder::read(boolean $sort = true, array|boolean $exceptions = false, boolean $fullPath = false)

Retourne un tableau du contenu du répertoire courant. Le tableau retourné contient deux sous-tableaux: Un des repertoires et un des fichiers:

$dir = new Folder(WWW_ROOT);
$files = $dir->read(true, ['files', 'index.php']);
/*
Array
(
    [0] => Array // dossiers
        (
            [0] => css
            [1] => img
            [2] => js
        )
    [1] => Array // fichiers
        (
            [0] => .htaccess
            [1] => favicon.ico
            [2] => test.php
        )
)
*/
Cake\Filesystem\Folder::realpath(string $path)

Récupère le vrai chemin (en prenant en compte « .. » etc…).

static Cake\Filesystem\Folder::slashTerm(string $path)

Retourne $path avec le slash ajouté à la fin (corrigé pour Windows ou d’autres OS).

Cake\Filesystem\Folder::tree(null|string $path = null, array|boolean $exceptions = true, null|string $type = null)

Retourne un tableau de répertoires imbriqués et de fichiers dans chaque répertoire.

L’API de File

class Cake\Filesystem\File(string $path, boolean $create = false, integer $mode = 755)
// Crée un nouveau fichier avec les permissions à 0644
$file = new File('/path/to/file.php', true, 0644);
property Cake\Filesystem\File::$Folder

L’objet Folder du fichier.

property Cake\Filesystem\File::$name

Le nom du fichier avec l’extension. Diffère de File::name() qui retourne le nom sans l’extension.

property Cake\Filesystem\File::$info

Un tableau du fichier info. Utilisez File::info() à la place.

property Cake\Filesystem\File::$handle

Contient le fichier de gestion des ressources si le fichier est ouvert.

property Cake\Filesystem\File::$lock

Active le blocage du fichier en lecture et en écriture.

property Cake\Filesystem\File::$path

Le chemin absolu du fichier courant.

Cake\Filesystem\File::append(string $data, boolean $force = false)

Ajoute la chaîne de caractères donnée au fichier courant.

Cake\Filesystem\File::close()

Ferme le fichier courant s’il est ouvert.

Cake\Filesystem\File::copy(string $dest, boolean $overwrite = true)

Copie le fichier vers $dest.

Cake\Filesystem\File::create()

Crée le fichier.

Cake\Filesystem\File::delete()

Supprime le fichier.

Cake\Filesystem\File::executable()

Retourne true si le fichier est exécutable.

Cake\Filesystem\File::exists()

Retourne true si le fichier existe.

Cake\Filesystem\File::ext()

Retourne l’extension du fichier.

Cake\Filesystem\File::Folder()

Retourne le dossier courant.

Cake\Filesystem\File::group()

Retourne le groupe du fichier ou false en cas d’erreur.

Cake\Filesystem\File::info()

Retourne l’info du fichier.

Cake\Filesystem\File::lastAccess()

Retourne l’heure du dernier d’accès.

Cake\Filesystem\File::lastChange()

Retourne l’heure de la dernière modification ou false en cas d’erreur.

Cake\Filesystem\File::md5(integer|boolean $maxsize = 5)

Récupère la checksum MD5 du fichier avec vérification préalable de la taille du fichier ou false en cas d’erreur.

Cake\Filesystem\File::name()

Retourne le nom du fichier sans l’extension.

Cake\Filesystem\File::offset(integer|boolean $offset = false, integer $seek = 0)

Définit ou récupère l’offset pour le fichier ouvert.

Cake\Filesystem\File::open(string $mode = 'r', boolean $force = false)

Ouvre le fichier courant avec un $mode donné.

Cake\Filesystem\File::owner()

Retourne le propriétaire du fichier.

Cake\Filesystem\File::perms()

Retourne le « chmod » (permissions) du Fichier.

static Cake\Filesystem\File::prepare(string $data, boolean $forceWindows = false)

Prépare une chaîne de caractères ascii pour l’écriture. Convertit les fins de lignes en caractère correct pour la plateforme courante. Si c’est Windows « \r\n » sera utilisé, toutes les autres plateformes utiliseront « \n ».

Cake\Filesystem\File::pwd()

Retourne un chemin complet du fichier.

Cake\Filesystem\File::read(string $bytes = false, string $mode = 'rb', boolean $force = false)

Retourne les contenus du fichier en chaîne de caractères ou retourne false en cas d’échec.

Cake\Filesystem\File::readable()

Retourne true si le fichier est lisible.

Cake\Filesystem\File::safe(string $name = null, string $ext = null)

Sécurise le nom de fichier pour la sauvegarde.

Cake\Filesystem\File::size()

Retourne la taille du fichier en octets.

Cake\Filesystem\File::writable()

Retourne true si le fichier est ouvert en écriture.

Cake\Filesystem\File::write(string $data, string $mode = 'w', boolean$force = false)

Ecrit le $data donné dans le fichier.

Cake\Filesystem\File::mime()

Récupère le mimetype du fichier, retourne false en cas d’échec.

Cake\Filesystem\File::replaceText($search, $replace)

Remplace le texte dans un fichier. Retourne false en cas d’échec et true en cas de succès.