Skip to content
Get packs

Guide · Open source

How to use Flysystem: install it and read, write and move files in PHP

Updated · written with AI from the project's own documentation and checked against our catalogue data

Flysystem is an open-source file storage library for PHP. It gives you one set of methods for working with files, whether they sit on the local disk, an FTP or SFTP server, or a cloud service such as AWS S3. This guide shows you how to install it with Composer, understand its adapter model, and use the core read and write methods so your code is not tied to one storage vendor.

Flysystemthephpleague/flysystem · ★ 13.6k · MIT

Quick start

  1. 1Check your PHP version. Confirm you have PHP 8.0.2 or newer, as stated in the README.
  2. 2Install Composer. Composer is required to install the package. Use it in your project directory.
  3. 3Install the package. Run composer require league/flysystem to add Flysystem to your project.
  4. 4Pick an adapter. Choose the storage backend you need, such as Local, FTP, SFTP or AWS S3.
  5. 5Read the API docs. Open the official filesystem API page to learn the read and write methods.
  6. 6Build a filesystem object. Pass your chosen adapter to Flysystem and use the same calls throughout your code.

What Flysystem is and when to use it

Flysystem provides one interface to interact with many types of filesystems. The project says that using it protects you from vendor lock-in and gives you a consistent experience across whichever storage suits your needs.

It is a code library, not a program with a user interface. It suits PHP developers who store files in more than one place, teams that want to avoid lock-in to one cloud provider, and projects that may move from local storage to S3 or similar later. If you only need simple local file reads and writes, PHP's built-in functions may be enough.

  • Best for: PHP developers storing files in more than one place
  • Best for: teams avoiding lock-in to a single cloud storage provider
  • Not for: non-PHP projects, since the library is written for PHP
  • Not for: end users looking for an application

Install Flysystem with Composer

Flysystem is installed as a PHP package through Composer, the package manager for PHP. The README lists PHP 8.0.2 or newer as the minimum version the project requires.

Run the install command from your project directory.

  • Prerequisites: PHP 8.0.2 or newer
  • Prerequisites: Composer
composer require league/flysystem

Understand adapters and the filesystem object

Flysystem separates the storage API from where the files actually live. Each storage location is handled by an adapter. The README lists officially supported adapters including Local, FTP, SFTP, Memory, AWS S3, AsyncAws S3, Google Cloud Storage, MongoDB GridFS, WebDAV and ZipArchive.

Your application code calls the same methods regardless of which adapter is behind them. If you need a storage backend that is not on the list, the project documents how to create an adapter yourself. Third-party adapters also exist for services such as Azure Blob Storage, Dropbox and OneDrive.

  • Local: files on the local disk
  • FTP and SFTP: files on remote servers
  • AWS S3 and Google Cloud Storage: cloud object storage
  • Memory: an in-memory store

Read and write files through the Flysystem API

Once you have an adapter, you create a filesystem object and use the Flysystem API to interact with files. The main usage reference is in the official documentation's filesystem API page, which describes the read, write and other file operations.

Because the calls stay the same when you change adapters, switching storage later mostly means changing the adapter setup rather than every file operation in your code.

Choose a storage adapter and plan for switching

Start with the adapter that matches your current storage, often Local during development. Keep storage-specific setup in one place so that moving to S3 or another backend later touches fewer files.

Check the official adapter documentation for the specific setup of each backend, since the README links to a separate page for each one.

  • Use the Local adapter for development on the local disk
  • Use the AWS S3 or Google Cloud Storage adapter for cloud storage
  • Read the adapter page for your backend before you configure it

Know what to read next

The README points to several official guides: what is new in V2/V3, the architecture overview, the filesystem API, and an upgrade guide from 1.x. If you are migrating older code, read the upgrade guide first.

Security issues should be reported by email to the maintainer rather than the public issue tracker, as the README asks.

  • What is new: flysystem.thephpleague.com/docs/what-is-new/
  • Architecture: flysystem.thephpleague.com/docs/architecture/
  • Filesystem API: flysystem.thephpleague.com/docs/usage/filesystem-api/

What people use it for

  • Storing uploaded files on the local disk during development, then moving them to AWS S3 in production
  • Saving files to an FTP or SFTP server from a PHP application
  • Keeping application code independent of a single cloud storage vendor
  • Writing files into a ZipArchive or in-memory store for testing

Frequently asked questions

Is Flysystem free to use?

Yes. Flysystem is released under the MIT licence, as shown in the project's README badge. The MIT licence is a permissive open-source licence; check the LICENSE file in the repository for the full terms.

What PHP version does Flysystem need?

The README states PHP 8.0.2 or newer. You also need Composer to install the package with composer require league/flysystem.

How do I install Flysystem?

Run composer require league/flysystem in your project directory. Composer is the package manager the project uses for installation.

Which storage services does Flysystem support?

The README lists officially supported adapters for Local, FTP, SFTP, Memory, AWS S3, AsyncAws S3, Google Cloud Storage, MongoDB GridFS, WebDAV and ZipArchive. Third-party adapters exist for services such as Azure Blob Storage, Dropbox and OneDrive.

How does Flysystem compare to Gaufrette or Laravel Filesystem?

Gaufrette is another PHP filesystem abstraction, and Laravel Filesystem is a wrapper around league/flysystem. PHP's built-in stream wrappers are an alternative for simple cases. The right choice depends on which adapters and framework you use.

Can I use Flysystem if I only need local file reads and writes?

You can, but PHP's built-in file functions may be enough for simple local-only work. Flysystem is most useful when you expect to store files in more than one place or switch storage later.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Flysystem suits PHP developers who need one file API across local disk, FTP, SFTP and cloud storage, or who want to avoid vendor lock-in. If your project is not in PHP, or you only read and write local files with no plans to change, PHP's built-in functions or another tool will likely be simpler.

Install options & downloads