Adapter Internals

Creating an adapter for Flysystem is pretty straightforward. An adapter must implement the League\Flysystem\AdapterInterface which expands upon the League\Flysystem\ReadInterface. For some easy fallbacks with streams and visibility defaults you can extend the League\Flysystem\Adapter\AbstractAdapter.

<?php

namespace Vendor\Namespace;

use League\Flysystem\Adapter\AbstractAdapter;

class MyAdapter extends AbstractAdapter
{
    // Implement all the method 
}

Return Format

When an Adapter returns any kind of meta data it should ALWAYS return in the format of an array. By doing so, it's possible to get the most out of every API call. Adapters like S3 will return pretty much everything in a single request. With caching enabled, holding back this information will lead to multiple API calls and by doing so impact performance.

Meta Data Values

key	description
type	file or dir
path	path to the file or dir
contents	file contents (string)
stream	stream (resource)
visibility	public or private
timestamp	modified time

When an adapter can not provide the metadata with the key that's required to satisfy the call, false should be returned.

Call flow logic

The Filesystem class orchestrates all the actions fired on an adapter. This centralises some of the routines and prevents adapters from dealing with certain situations. Because the Filesystem class caches the results, either in memory (per request / instance) or persistent, a great speed improvement is achieved. The following assumptions can be made:

• A file will be absent when a write or writeStream method is called.
• A file will be present when a update, updateStream, delete method is called.

Expected behaviour in handling directory creation during writes

In many new-age filesystems directories are non-existing or second class citizens. Therefor adapters should implicitly create directories when a write or writeStream method is called. This ensures the behaviour is consistent across the different adapters.

Expected behaviour when listing contents.

The result of the listContents must always contain the full path of the root specified in the adapter. When adapters don't support directories (linear filesystem / key => value stores) the directory structure can be emulated using the League\Flysystem\Util::emulateDirectories helper. This will ensure the existence of all parent directories in the result set.

Exception Handling

Exceptions from underlying packages should NOT be caught in case of actual unexpected behaviour. Some adapters will throw a message when a file is not found, which is always possible. This exception will be caught as it is expected behaviour.