Flysystem by @frankdejonge

Flysystem is a filesystem abstraction which allows you to easily swap out a local filesystem for a remote one.

Goals

Have a generic API for handling common tasks across multiple file storage engines.
Have consistent output which you can rely on.
Integrate well with other packages/frameworks.
Be cacheable.
Emulate directories in systems that support none, like AwsS3.
Support third party plugins.
Make it easy to test your filesystem interactions.
Support streams for bigger file handling

Installation

Through Composer, obviously:

{
    "require": {
        "frenkynet/flysystem": "0.1.*"
    }
}

Adapters

Local
Amazon Web Services - S3
Dropbox
Ftp
Sftp (through phpseclib)
Zip (through ZipArchive)
WebDAV (through SabreDAV)

Planned Adapters

Azure
PR's welcome?

Caching

Memory (array caching)
Redis (through Predis)
Memcached

Local Setup

use Flysystem\Filesystem;
use Flysystem\Adapter\Local as Adapter;

$filesystem = new Filesystem(new Adapter(__DIR__.'/path/to/root'));

Zip Archive Setup

use Flysystem\Filesystem;
use Flysystem\Adapter\Zip as Adapter;

$filesystem = new Filesystem(new Adapter(__DIR__.'/path/to/archive.zip'));

AwsS3 Setup

use Aws\S3\S3Client;
use Flysystem\Filesystem;
use Flysystem\Adapter\AwsS3 as Adapter;

$client = S3Client::factory(array(
    'key'    => '[your key]',
    'secret' => '[your secret]',
));

$filesystem = new Filesystem(new Adapter($client, 'bucket-name', 'optional-prefix'));

Dropbox Setup

use Dropbox\Client;
use Flysystem\Filesystem;
use Flysystem\Adapter\Dropbox as Adapter;

$client = new Client($token, $appName);
$filesystem = new Filesystem(new Adapter($client, 'optional/path/prefix'));

Ftp Setup

use Flysystem\Filesystem;
use Flysystem\Adapter\Ftp as Adapter;

$filesystem = new Filesystem(new Adapter(array(
	'host' => 'ftp.example.com',
	'port' => 21,
	'username' => 'username',
	'password' => 'password',
	'root' => '/path/to/root',
	'passive' => true,
	'ssl' => true,
	'timeout' => 30,
)));

Sftp Setup

use Flysystem\Filesystem;
use Flysystem\Adapter\Sftp as Adapter;

$filesystem = new Filesystem(new Adapter(array(
	'host' => 'example.com',
	'port' => 21,
	'username' => 'username',
	'password' => 'password',
	'privateKey' => 'path/to/or/contents/of/privatekey',
	'root' => '/path/to/root',
	'timeout' => 10,
)));

WebDAV Setup

$client = new Sabre\DAV\Client($settings);
$adapter = new Flysystem\Adapter\WebDav($client);
$flysystem = new Flisystem\Filesystem($adapter);

Predis Caching Setup

use Flysystem\Filesystem;
use Flysystem\Adapter\Local as Adapter;
use Flysystem\Cache\Predis as Cache;

$filesystem = new Filesystem(new Adapter(__DIR__.'/path/to/root'), new Cache);

// Or supply a client
$client = new Predis\Client;
$filesystem = new Filesystem(new Adapter(__DIR__.'/path/to/root'), new Cache($client));

Memcached Caching Setup

use Flysystem\Filesystem;
use Flysystem\Adapter\Local as Adapter;
use Flysystem\Cache\Memcached as Cache;

$memcached = new Memcached;
$memcached->addServer('localhost', 11211);
$filesystem = new Filesystem(new Adapter(__DIR__.'/path/to/root'), new Cache($memcached, 'storageKey', 300));
// Storage Key and expire time are optional

General Usage

Write Files

$filemanager->write('filename.txt', 'contents');

Update Files

$filemanager->update('filename.txt', 'new contents');

Write or Update Files

$filemanager->put('filename.txt', 'contents');

Read Files

$contents = $filemanager->read('filename.txt');

Check if a file exists

$exists = $filemanager->has('filename.txt');

Delete Files

$filemanager->delete('filename.txt');

Rename Files

$filemanager->rename('filename.txt', 'newname.txt');

Get Mimetypes

$mimetype = $filemanager->getMimetype('filename.txt');

Get Timestamps

$timestamp = $filemanager->getTimestamp('filename.txt');

Get File Sizes

$size = $filemanager->getSize('filename.txt');

Create Directories

$filemanager->createDir('nested/directory');

Directories are also made implicitly when writing to a deeper path

$filemanager->write('path/to/filename.txt', 'contents');

Delete Directories

$filemanager->deleteDir('path/to/directory');

Manage Visibility

Visibility is the abstraction of file permissions across multiple platforms. Visibility can be either public or private.

use Flysystem\AdapterInterface;
$filesystem->write('db.backup', $backup, AdapterInterface::VISIBILITY_PRIVATE);
// or simply
$filesystem->write('db.backup', $backup, 'private');

You can also change and check visibility of existing files

if ($filesystem->getVisibility('secret.txt') === 'private') {
	$filesystem->setVisibility('secret.txt', 'public');
}

List Contents

$contents = $filemanager->listContents();

The result of a contents listing is a collection of arrays containing all the metadata the file manager knows at that time. By default a you'll receive path info and file type. Additional info could be supplied by default depending on the adapter used.

Example:

foreach ($contents as $object) {
	echo $object['basename'].' is located at'.$object['path'].' and is a '.$object['type'];
}

By default Flysystem lists the top directory non-recursively. You can supply a directory name and recursive boolean to get more precise results

$contents = $flysystem->listContents('some/dir', true);

List paths

$paths = $filemanager->listPaths();

foreach ($paths as $path) {
	echo $path;
}

List with ensured presence of specific metadata

$listing = $flysystem->listWith(['mimetype', 'size', 'timestamp'], 'optional/path/to/dir', true);

foreach ($listing as $object) {
	echo $object['path'].' has mimetype: '.$object['mimetype'];
}

Get file into with explicid metadata

$info = $flysystem->getWithMetadata('path/to/file.txt', ['timestamp', 'mimetype']);
echo $info['mimetype'];
echo $info['timestamp'];

Using streams for reads and writes

$stream = fopen('/path/to/database.backup', 'r+');
$flysystem->writeStream('backups/' . strftime('%G-%m-%d') . '.backup', $stream);

// Using write you can also directly set the visibility
$flysystem->writeStream('backups/' . strftime('%G-%m-%d') . '.backup', $stream, 'private');

// Or update a file with stream contents
$flysystem->updateStream('backups/' . strftime('%G-%m-%d') . '.backup', $stream);

$stream = $flysystem->readStream('something/is/here.ext');
$contents = stream_get_contents($stream);
fclose($stream);

Plugins

Need a feature which is not included in Flysystem's bag of trick? Write a plugin!

use Flysystem\FilesystemInterface;
use Flysystem\PluginInterface;

class MaximusAwesomeness implements PluginInterface
{
    protected $filesystem;

    public function setFilesystem(FilesystemInterface $filesystem)
    {
        $this->filesystem = $filesystem;
    }

    public function getMethod()
    {
        return 'getDown';
    }

    public function handle($path = null)
    {
        $contents = $this->filesystem->read($path);

        return sha1($contents);
    }
}

Now we're ready to use the plugin

use Flysystem\Filesystem;
use Flysystem\Adapter;

$filesystem = new Filesystem(new Adapter\Local(__DIR__.'/path/to/files/'));
$filesystem->addPlugin(new MaximusAwesomeness);
$sha1 = $filesystem->getDown('path/to/file');

dragoonis/Flysystem