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

当使用传统的Amazon S3适配器时，您需要指定CA证书才能在https中与Amazon服务器通信。您可以在创建\AmazonS3对象之前定义它来使用随SDK提供的CA证书。

define("AWS_CERTIFICATE_AUTHORITY", true);

当使用Gaufrette\Adapter\AmazonS3适配器时，不需要指定自定义CA证书，因为它使用最新的AWS SDK for PHP版本。

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

使用AzureBlobStorage

Azure Blob Storage是Microsoft Windows Azure云环境提供的存储服务。要使用此适配器，您需要在项目中安装Azure SDK for php。

要实例化AzureBlobStorage适配器，您需要一个BlobProxyFactoryInterface实例（您可以使用默认的BlobProxy类）和一个连接字符串。连接字符串应遵循以下原型

BlobEndpoint=https://XXXXXXXXXX.blob.core.windows.net/;AccountName=XXXXXXXX;AccountKey=XXXXXXXXXXXXXXXXXXXX

您应该在您的Windows Azure管理控制台中找到您的endpoint、account name和account key。

由于blob代理工厂，适配器会延迟加载到端点的连接，因此它将不会在真正需要时创建任何连接（例如，当执行读取或写入操作时）。

以下是如何构建适配器的一个简单示例

$connectionString = '...';
$factory = new Gaufrette\Adapter\AzureBlobStorage\BlobProxyFactory($connectionString);
$adapter = new Gaufrette\Adapter\AzureBlobStorage($factory, 'my-container');
$filesystem = new Gaufrette\Filesystem($adapter);

使用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/aws/aws-sdk-php

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

<service id="acme.s3"
         class="Aws\\S3\\S3Client"
         factory-class="Aws\\S3\\S3Client"
         factory-method="factory">
    <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>

流式文件

有时，你没有选择，你必须获取一个可流式传输的文件 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

它是否是绿色的？