Flysystem for PHP: Complete Guide with Examples

What is Flysystem and why is it needed?

\n\n

Flysystem is a powerful PHP library that provides a single, unified interface for working with various file systems. Developed by Frank de Jonge, it solves a fundamental problem: in real projects, code is often tightly coupled to a specific file system (local disk, FTP, Amazon S3, Dropbox, etc.). If tomorrow you need to move file storage from a local server to cloud storage, you would have to rewrite a significant portion of the code.

\n\n

Flysystem abstracts this complexity. You write the code once using a unified API, and you can change the file system "adapter" (driver) without altering the application's business logic. This makes your code:

\n

\n
• Flexible — easily switch between storage options.
\n
• Testable — you can use a "fake" file system in tests.
\n
• Portable — code works the same across different environments.
\n

\n\n

The library is used in well-known projects such as Laravel (as the basis for the storage disk), Symfony, Drupal, and many others. Flysystem supports dozens of adapters: Local, FTP/SFTP, Amazon S3, Google Cloud Storage, Azure Blob Storage, WebDAV, Dropbox, and even encrypted and Zip archives.

\n\n

Installation

\n\n

Flysystem is installed via Composer. For basic work with the local file system, two packages are sufficient:

\n\n

composer require league/flysystem\ncomposer require league/flysystem-local

\n\n

Important: Starting from version 3.x, Flysystem uses a modular architecture. The main package league/flysystem contains only interfaces and base classes. Adapters (drivers) are installed separately. This allows you to include only what you actually need.

\n\n

For other file systems:

\n

\n
• composer require league/flysystem-ftp — for FTP/SFTP
\n
• composer require league/flysystem-aws-s3-v3 — for Amazon S3
\n
• composer require league/flysystem-google-cloud-storage — for Google Cloud
\n
• composer require league/flysystem-memory — for testing (virtual in-memory FS)
\n

\n\n

Quick Start

\n\n

Let's create a simple example: writing, reading, and deleting a file on the local disk.

\n\n

<?php\nrequire 'vendor/autoload.php';\n\nuse League\\Flysystem\\Filesystem;\nuse League\\Flysystem\\Local\\LocalFilesystemAdapter;\n\n// 1. Create an adapter for the local file system\n// Specify the root directory where files will be stored\n$adapter = new LocalFilesystemAdapter(__DIR__ . '/storage');\n\n// 2. Create a Filesystem instance\n$filesystem = new Filesystem($adapter);\n\n// 3. Write a file\n$filesystem->write('hello.txt', 'Hello, world!');\n\n// 4. Read the file\n$content = $filesystem->read('hello.txt');\necho $content; // Outputs: Hello, world!\n\n// 5. Check if the file exists\nif ($filesystem->fileExists('hello.txt')) {\n    echo "File exists!";\n}\n\n// 6. Delete the file\n$filesystem->delete('hello.txt');\n\n// 7. Check that the file is gone\necho $filesystem->fileExists('hello.txt') ? 'Exists' : 'Does not exist'; // Outputs: Does not exist\n?>

\n\n

Note: we are not using file_put_contents(), fopen(), or other native PHP functions. All code works through the unified Filesystem interface.

\n\n

Main Methods/Functions

\n\n

Let's look at the key Flysystem methods. All examples assume you already have a $filesystem object created.

\n\n

1. write() — Writing a new file

\n

What it does: Creates a new file or overwrites an existing one.

\n

Parameters:

\n

\n
• string $path — path to the file
\n
• string|resource $contents — file contents (string or