README

Flysystem 是一种文件系统抽象，允许您轻松地将本地文件系统与远程文件系统进行交换。

Flysystem 在 Packagist 上的信息

支持 Flysystem

您经常使用 Flysystem 吗？通过 Gittip 支持它将帮助我腾出额外的时间来修复错误、开发新功能和编写文档。

目标

• 为处理多个文件存储引擎中的常见任务提供一个通用的 API。
• 提供一致的输出，您可以信赖。
• 与其他包/框架很好地集成。
• 可缓存。
• 在支持none的系统（如 AwsS3）中模拟目录。
• 支持第三方插件。
• 使测试文件系统交互变得容易。
• 支持流以处理更大的文件。

安装

通过 Composer，显然。

{
    "require": {
        "league/flysystem": "0.4.*"
    }
}

您也可以通过注册自动加载器函数来使用 Flysystem 而不使用 Composer。

spl_autoload_register(function($class) {
    if (!substr($class, 0, 17) === 'League\\Flysystem') {
        return;
    }

    $location = __DIR__ . 'path/to/flysystem/src/' . str_replace('\\', '/', $class) . '.php';

    if (is_file($location)) {
        require_once($location);
    }
});

适配器

• 本地
• 亚马逊网络服务 - S3
• Rackspace 云文件
• Dropbox
• Ftp
• Sftp（通过 phpseclib）
• Zip（通过 ZipArchive）
• WebDAV（通过 SabreDAV）
• NullAdapter

计划中的适配器

• Azure
• 欢迎PR？

缓存

• 内存（数组缓存）
• Redis（通过 Predis）
• Memcached
• 适配器

本地设置

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

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

Zip存档设置

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

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

AWS S3 设置

use Aws\S3\S3Client;
use League\Flysystem\Filesystem;
use League\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'));

Rackspace 设置

use OpenCloud\OpenStack;
use OpenCloud\Rackspace;
use League\Flysystem\Filesystem;
use League\Flysystem\Adapter\Rackspace as Adapter;

$client = new OpenStack(Rackspace::UK_IDENTITY_ENDPOINT, array(
    'username' => ':username',
    'password' => ':password',
));

$store = $client->objectStoreService('cloudFiles', 'LON');
$container = $store->getContainer('flysystem');

$filesystem = new Filesystem(new Adapter($container));

您还可以使用前缀来“命名空间”您的文件系统。

$filesystem = new Filesystem(new Adapter\Rackspace($container, 'prefix'));

Dropbox 设置

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

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

FTP 设置

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

$filesystem = new Filesystem(new Adapter(array(
    'host' => 'ftp.example.com',
    'username' => 'username',
    'password' => 'password',

    /** optional config settings */
    'port' => 21,
    'root' => '/path/to/root',
    'passive' => true,
    'ssl' => true,
    'timeout' => 30,
)));

SFTP 设置

use League\Flysystem\Filesystem;
use League\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 设置

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

NullAdapter 设置

此适配器类似于 /dev/null，您只能写入它。从它读取永远不可能。

$adapter = new League\Flysystem\Adapter\NullAdapter;
$flysystem = new League\Flysystem\Filesystem($adapter);

Predis 缓存设置

use League\Flysystem\Filesystem;
use League\Flysystem\Adapter\Local as Adapter;
use League\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 缓存设置

use League\Flysystem\Filesystem;
use League\Flysystem\Adapter\Local as Adapter;
use League\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

适配器缓存设置

use Dropbox\Client;
use League\Flysystem\Filesystem;
use League\Flysystem\Adapter\Dropbox;
use League\Flysystem\Adapter\Local;
use League\Flysystem\Cache\Adapter;

$client = new Client('token', 'app');
$dropbox = new Dropbox($client, 'prefix');

$local = new Local('path');
$cache = new Adapter($local, 'file', 300);
// Expire time is optional

$filesystem = new Filesystem($dropbox, $cache);

通用用法

写入文件

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

更新文件

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

写入或更新文件

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

读取文件

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

检查文件是否存在

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

删除文件

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

重命名文件

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

获取 MIME 类型

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

获取时间戳

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

获取文件大小

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

创建目录

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

在写入更深路径时也会隐式创建目录

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

删除目录

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

管理可见性

可见性是跨多个平台文件权限的抽象。可见性可以是公开的或私有的。

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

您还可以更改和检查现有文件的可见性

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

全局可见性设置

您可以将可见性设置为默认值，这可以防止您到处设置它。

$filesystem = new League\Flysystem\Filesystem($adapter, $cache, [
    'visibility' => AdapterInterface::VISIBILITY_PRIVATE
]);

列出内容

$contents = $filemanager->listContents();

内容列表的结果是包含文件管理器在此时所知道的所有元数据的数组集合。默认情况下，您将收到路径信息和文件类型。根据使用的适配器，默认情况下可能还会提供其他信息。

示例

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

默认情况下，Flysystem 以非递归方式列出顶级目录。您可以通过提供目录名称和递归布尔值来获取更精确的结果

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

列出路径

$paths = $filemanager->listPaths();

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

列出具有确保存在特定元数据的

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

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

使用显式元数据获取文件

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

使用流进行读写

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

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

// Create or overwrite using a stream.
$putStream = tmpfile();
fwrite($putStream, $contents);
rewind($putStream);
$filesystem->putStream('somewhere/here.txt', $putStream);
fclose($putStream);

S3 和 writeStream

为了获取对象的正确 MIME 类型，请按如下方式提供

$s3->writeStream('path/to/object.png', $stream, [
    'visibility' => 'public',
    'mimetype' => 'image/png',
]);

插件

需要 Flysystem 中的技巧包中未包含的功能？编写一个插件！

use League\Flysystem\FilesystemInterface;
use League\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);
    }
}

现在我们可以使用插件了

use League\Flysystem\Filesystem;
use League\Flysystem\Adapter;

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

挂载管理器

Flysystem 提供了一个包装类，可以轻松地从单个对象中管理多个文件系统实例。 Flysystem\MountManager 是一个易于使用的容器，允许您简化复杂的跨文件系统交互。

设置 Mount Manager 很简单

$ftp = new League\Flysystem\Filesystem($ftpAdapter);
$s3 = new League\Flysystem\Filesystem($s3Adapter);
$local = new League\Flysystem\Filesystem($localAdapter);

// Add them in the constructor
$manager = new League\Flysystem\MountManager(array(
    'ftp' => $ftp,
    's3' => $s3,
));

// Or mount them later
$manager->mountFilesystem('local', $local);

现在我们可以在 Flysystem\Filesystem 实例上执行所有通常的文件操作。

// Read from FTP
$contents = $manager->read('ftp://some/file.txt');

// And write to local
$manager->write('local://put/it/here.txt', $contents);

这使得编写简单的同步策略变得容易。

$contents = $manager->listContents('local://uploads', true);

foreach ($contents as $entry) {
    $update = false;

    if ( ! $manager->has('storage://'.$entry['path'])) {
        $update = true;
    }

    elseif ($manager->getTimestamp('local://'.$entry['path']) > $manager->getTimestamp('storage://'.$entry['path'])) {
        $update = true;
    }

    if ($update) {
        $manager->put('storage://'.$entry['path'], $manager->read('local://'.$entry['path']));
    }
}

欢迎使用。

哦，如果您已经看到了这里，不妨关注我的 twitter。