README

Gaufrette 是一个PHP5库，提供文件系统抽象层。

该项目正在积极开发中，但我们不想破坏BC。

为什么使用 Gaufrette？

想象一下，你需要在PHP项目中管理大量媒体。让我们看看如何使用 Gaufrette 利用这种情况。

文件系统抽象层允许你在不知道所有这些媒体将存储在哪里以及如何存储的情况下开发你的应用程序。

此方法的另一个优点是，您可以更新文件位置，而无需更改代码（除了文件系统的定义）。例如，如果您的项目增长非常快，服务器达到其限制，您可以轻松地将媒体移动到Amazon S3服务器或其他任何解决方案。

试试！

设置您的文件系统

以下是一个使用本地文件系统适配器的示例。要设置其他适配器，请查看 测试用例。

<?php

use Gaufrette\Filesystem;
use Gaufrette\Adapter\Local as LocalAdapter;

$adapter = new LocalAdapter('/var/media');
$filesystem = new Filesystem($adapter)

使用文件系统

<?php

// ... setup your filesystem

$content = $filesystem->read('myFile');

$content = 'Hello I am the new content';

$filesystem->write('myFile', $content);

使用文件对象

Gaufrette 还提供了一个 File 类，它表示文件系统中的文件

<?php

$file = new File('newFile', $filesystem);
$file->setContent('Hello World');

echo $file->getContent(); // Hello World

缓存慢速文件系统

如果您必须处理慢速文件系统，则直接使用它是不切实际的。因此，您需要缓存！幸运的是，Gaufrette 提供了一个现成的缓存系统。它由两个适配器本身组成

* The *source* adapter that should be cached
* The *cache* adapter that is used to cache

以下是如何缓存 ftp 文件系统的示例

<?php

use Gaufrette\Filesystem;
use Gaufrette\Adapter\Ftp as FtpAdapter;
use Gaufrette\Adapter\Local as LocalAdapter;
use Gaufrette\Adapter\Cache as CacheAdapter;

// Locale Cache-Directory (e.g. '%kernel.root_dir%/cache/%kernel.environment%/filesystem') with create = true
$local = new LocalAdapter($cacheDirectory, true);
// FTP Adapter with a defined root-path
$ftp = new FtpAdapter($path, $host, $username, $password, $port);

// Cached Adapter with 3600 seconds time to live
$cachedFtp = new CacheAdapter($ftp, $local, 3600);

$filesystem = new Filesystem($cachedFtp);

缓存适配器的第三个参数是缓存的有效期。

使用 Amazon S3

您需要指定一个CA证书，以便能够通过https与Amazon服务器通信。您可以使用SDK中提供的证书，在创建 \AmazonS3 对象之前定义

define("AWS_CERTIFICATE_AUTHORITY", true);

使用 OpenCloud

要使用 OpenCloud 适配器，您需要使用 OpenCloud SDK 创建连接。然后您可以获取 OpenCloud 适配器所需的 ObjectStore。

OpenCloud

$connection = new OpenCloud\OpenStack(
    'https://example.com/v2/identity',
    array(
        'username' => 'your username',
        'password' => 'your Keystone password',
        'tenantName' => 'your tenant (project) name'
    ));

$objectStore = $connection->ObjectStore('cloudFiles', 'LON', 'publicURL');

$adapter = new Gaufrette\Adapter\OpenCloud(
    $objectStore,
    'container-name'
);

$filesystem = new Filesystem($adapter);

Rackspace

Rackspace 使用不同的连接类

$connection = new OpenCloud\Rackspace(
     'https://identity.api.rackspacecloud.com/v2.0/',
     array(
         'username' => 'rackspace-user',
         'apiKey' => '0900af093093788912388fc09dde090ffee09'
     ));

使用 FTP 适配器

某些 FTP 服务器需要有效的配置，以便 Gaufrette 能够按预期与它们一起工作。

Pure Ftpd

要处理隐藏文件，我们需要通过以下方式来配置：

echo "yes" > /etc/pure-ftpd/conf/DisplayDotFiles

Proftpd

为了处理隐藏文件，我们需要更改 proftpd 配置文件中的 ListOptions（在 Debian 系统中可能是 /etc/proftpd/proftpd.conf）为：

ListOptions  "-la"

在 Symfony2 项目中使用 Gaufrette

如你所见，Gaufrette 提供了一种优雅的方式来声明你的文件系统。

在你的 Symfony2 项目中，将以下代码添加到 deps

[gaufrette]
    git=https://github.com/KnpLabs/Gaufrette.git

# if you want to use Amazon S3
[aws-sdk]
    git=https://github.com/amazonwebservices/aws-sdk-for-php

以及 app/autoload.php 文件的末尾

// AWS SDK needs a special autoloader
require_once __DIR__.'/../vendor/aws-sdk/sdk.class.php';

然后，你可以简单地将它们添加为依赖注入容器的服务。以下是一个使用 Amazon S3 的服务声明示例

<service id="acme.s3" class="AmazonS3">
    <argument type="collection">
        <argument key="key">%acme.aws_key%</argument>
        <argument key="secret">%acme.aws_secret_key%</argument>
    </argument>
</service>

<service id="acme.s3.adapter" class="Gaufrette\Adapter\AmazonS3">
    <argument type="service" id="acme.s3"></argument>
    <argument>%acme.s3.bucket_name%</argument>
</service>

<service id="acme.fs" class="Gaufrette\Filesystem">
    <argument type="service" id="acme.s3.adapter"></argument>
</service>

别忘了设置常量，让 AWS SDK 使用其 CA 证书（在创建 \AmazonS3 对象之前将被执行的某个地方）

define("AWS_CERTIFICATE_AUTHORITY", true);
$fs = $container->get('acme.fs');
// use $fs

流式文件

有时候，你不得不这样做，你必须获取一个可流式传输的文件 URL（例如，为了转换图像）。让我们看看以下示例

$adapter = new InMemoryAdapter(array('hello.txt' => 'Hello World!'));
$filesystem = new Filesystem($adapter);

$map = StreamWrapper::getFilesystemMap();
$map->set('foo', $filesystem);

StreamWrapper::register();

echo file_get_contents('gaufrette://foo/hello.txt'); // Says "Hello World!"

运行测试

这些测试使用了 phpspec2 和 PHPUnit。

设置供应商库

由于一些文件系统适配器使用供应商库，你应该安装供应商库

$ cd gaufrette
$ php composer.phar install --dev
$ sh bin/configure_test_env.sh

这将避免跳过许多测试。

启动测试套件

在 Gaufrette 根目录下

检查类规范是否通过：$ php bin/phpspec run

检查适配器的基本功能（适配器应该配置好，你会看到很多跳过的测试）：$ phpunit

它变绿了吗？