readme.md

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');

Enjoy.