Flysystem PHP : guide complet avec exemples

Qu'est-ce que Flysystem et pourquoi l'utiliser ?

Flysystem est une bibliothèque PHP puissante qui offre une interface unique et unifiée pour travailler avec différents systèmes de fichiers. Développée par Frank de Jonge, elle résout un problème fondamental : dans les projets réels, le code est souvent fortement couplé à un système de fichiers spécifique (disque local, FTP, Amazon S3, Dropbox, etc.). Si demain vous devez migrer le stockage de fichiers d'un serveur local vers le cloud, vous devrez réécrire une partie importante de votre code.

Flysystem abstrait cette complexité. Vous écrivez le code une seule fois, en utilisant une API commune, et vous pouvez changer l'adaptateur (pilote) du système de fichiers sans modifier la logique métier de votre application. Cela rend votre code :

• Flexible — basculez facilement entre différents stockages.
• Testable — utilisez un système de fichiers "factice" dans vos tests.
• Portable — le code fonctionne de manière identique dans différents environnements.

Cette bibliothèque est utilisée dans des projets célèbres comme Laravel (comme base pour le disque de stockage), Symfony, Drupal et bien d'autres. Flysystem supporte des dizaines d'adaptateurs : Local, FTP/SFTP, Amazon S3, Google Cloud Storage, Azure Blob Storage, WebDAV, Dropbox, et même les archives chiffrées et Zip.

Installation

Flysystem s'installe via Composer. Pour une utilisation de base avec le système de fichiers local, deux paquets suffisent :

composer require league/flysystem
composer require league/flysystem-local

Important : Depuis la version 3.x, Flysystem utilise une architecture modulaire. Le paquet principal league/flysystem contient uniquement les interfaces et les classes de base. Les adaptateurs (pilotes) s'installent séparément. Cela permet de n'inclure que ce dont vous avez réellement besoin.

Pour les autres systèmes de fichiers :

• composer require league/flysystem-ftp — pour FTP/SFTP
• composer require league/flysystem-aws-s3-v3 — pour Amazon S3
• composer require league/flysystem-google-cloud-storage — pour Google Cloud
• composer require league/flysystem-memory — pour les tests (système de fichiers virtuel en mémoire)

Démarrage rapide

Créons un exemple simple : écrire, lire et supprimer un fichier sur le disque local.

<?php
require 'vendor/autoload.php';

use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;

// 1. Créer un adaptateur pour le système de fichiers local
// Spécifier le répertoire racine où les fichiers seront stockés
$adapter = new LocalFilesystemAdapter(__DIR__ . '/storage');

// 2. Créer une instance de Filesystem
$filesystem = new Filesystem($adapter);

// 3. Écrire un fichier
$filesystem->write('bonjour.txt', 'Bonjour le monde !');

// 4. Lire le fichier
$content = $filesystem->read('bonjour.txt');
echo $content; // Affiche : Bonjour le monde !

// 5. Vérifier si le fichier existe
if ($filesystem->fileExists('bonjour.txt')) {
    echo "Le fichier existe !";
}

// 6. Supprimer le fichier
$filesystem->delete('bonjour.txt');

// 7. Vérifier que le fichier a bien été supprimé
echo $filesystem->fileExists('bonjour.txt') ? 'Existe' : 'N\'existe pas'; // Affiche : N'existe pas
?>

Remarquez que nous n'utilisons pas file_put_contents(), fopen() ou d'autres fonctions PHP natives. Tout le code passe par l'interface unique Filesystem.

Méthodes principales

Examinons les méthodes clés de Flysystem. Tous les exemples supposent que vous avez déjà créé un objet $filesystem.

1. write() — Écrire un nouveau fichier

Fonction : Crée un nouveau fichier ou écrase un fichier existant.

Paramètres :

• string $path — chemin du fichier
• string|resource $contents — contenu du fichier (chaîne ou ressource)
• array $config — paramètres optionnels (par exemple