README

Cabinet是一个PHP 5.3+库，提供了一个简单的文件存储层。

它提供了一致的API来存储和检索文件，以及获取文件的基本信息，如文件大小和内容类型。

这很有用，如果你

• 想要编写具有可配置文件存储后端的可重用组件
• 你想要确保文件存储的可扩展性（例如，你可以从开始存储你的文件在服务器文件系统，然后切换到Amazon S3）

Cabinet提供了对PHP流和Amazon S3的适配器，无需额外安装。但你可以很容易地通过实现DotsUnited\Cabinet\Adapter\AdapterInterface来编写自己的适配器。

安装

Cabinet可以使用Composer工具安装。您可以将dotsunited/cabinet添加到composer.json中的依赖项中，或者如果您想将Cabinet作为独立包安装，请转到主目录并运行

$ wget https://getcomposer.org.cn/composer.phar
$ php composer.phar install

然后，您可以使用Composer生成的自动加载器来访问Cabinet类

<?php
require 'vendor/autoload.php';
?>

用法

Cabinet适配器的实例可以直接创建或使用静态方法DotsUnited\Cabinet\Cabinet::factory()创建。

使用Cabinet适配器构造函数

您可以使用构造函数创建适配器的实例。适配器构造函数接受一个参数，即配置参数的数组。

<?php
$adapter = new \DotsUnited\Cabinet\Adapter\StreamAdapter(array(
    'base_path' => '/my/base/path',
    'base_uri'  => 'http://static.example.com'
));
?>

使用Cabinet工厂

作为直接使用适配器构造函数的替代方案，您可以使用静态方法DotsUnited\Cabinet\Cabinet::factory()创建适配器的实例。

第一个参数是一个字符串，用于指定适配器类（例如 '\DotsUnited\Cabinet\Adapter\StreamAdapter'）。第二个参数是传递给适配器构造函数的相同参数数组。

<?php
$adapter = \DotsUnited\Cabinet\Cabinet::factory('\DotsUnited\Cabinet\Adapter\StreamAdapter', array(
    'base_path' => '/my/base/path',
    'base_uri'  => 'http://static.example.com'
));
?>

或者，第一个参数可以是一个关联数组。适配器类从“适配器”键读取。可选地，它可以包含一个“配置”键，包含配置参数。在这种情况下，第二个参数将被忽略。

<?php
$adapter = \DotsUnited\Cabinet\Cabinet::factory(array(
    'adapter' => '\DotsUnited\Cabinet\Adapter\StreamAdapter',
    'config' => array(
        'base_path' => '/my/base/path',
        'base_uri'  => 'http://static.example.com'
    )
));
?>

管理文件

创建适配器后，您可以使用以下方法存储、检索和获取有关文件的信息

导入外部本地文件

<?php
$adapter->import($external, $file);
?>

将数据写入文件

<?php
$adapter->write($file, $data);
?>

从文件中读取数据

<?php
$adapter->read($file);
?>

为文件获取只读流资源

<?php
$adapter->stream($file);
?>

内部复制文件

<?php
$adapter->copy($src, $dest);
?>

内部重命名文件

<?php
$adapter->rename($src, $dest);
?>

删除文件

<?php
$adapter->unlink($file);
?>

检查文件是否存在

<?php
$adapter->exists($file);
?>

获取文件大小

<?php
$adapter->size($file);
?>

获取文件MIME内容类型

<?php
$adapter->type($file);
?>

获取给定文件的Web可访问URI

<?php
$adapter->uri($file);
?>

适配器

Cabinet提供了两个适配器

• DotsUnited\Cabinet\Adapter\StreamAdapter用于PHP流
• DotsUnited\Cabinet\Adapter\AmazonS3Adapter用于Amazon S3

每个适配器都接受自己的配置参数集，这些参数可以作为关联数组传递给构造函数。

DotsUnited\Cabinet\Adapter\StreamAdapter

DotsUnited\Cabinet\Adapter\StreamAdapter的配置参数

• base_path：存储文件的路径。
• base_uri：您的文件公开可访问的Uri。
• directory_umask：适配器创建的目录的umask（默认为0700）。
• file_umask：适配器创建的文件的umask（默认为0600）。
• stream_context：用于文件系统函数的流上下文。这可以是使用stream_context_create()创建的资源，或者是一个包含上下文选项的数组。
• mime_type_detector：用于检测MIME内容类型的DotsUnited\Cabinet\MimeType\Detector\DetectorInterface实例。这是可选的，默认为DotsUnited\Cabinet\MimeType\Detector\Fileinfo。
• filename_filter：一个DotsUnited\Cabinet\Filter\FilterInterface的实例。文件名过滤器在下一节中解释。

DotsUnited\Cabinet\Adapter\AmazonS3Adapter

DotsUnited\Cabinet\Adapter\AmazonS3Adapter的配置参数

• s3_client：一个Aws\S3\S3Client实例（参见AWS SDK文档）。
• bucket：存储文件的存储桶。
• storage_class：文件的存储类设置。允许的值：STANDARD、REDUCED_REDUNDANCY。默认值为STANDARD。
• acl：文件的ACL设置。允许的值：private、public-read、public-read-write、authenticated-read、bucket-owner-read、bucket-owner-full-control。默认值为private。
• uri_expiration_time：如果您存储私有文件，则Web可访问URI的过期时间。这可以是一个时间戳或可以被strtotime()解析的字符串。
• throw_exceptions：一个布尔值，指示是否抛出异常（来自Aws\S3\S3Client的异常被捕获并重新抛出为\RuntimeException）。
• mime_type_detector：用于检测MIME内容类型的DotsUnited\Cabinet\MimeType\Detector\DetectorInterface实例。这是可选的，默认为DotsUnited\Cabinet\MimeType\Detector\Fileinfo。
• filename_filter：一个DotsUnited\Cabinet\Filter\FilterInterface的实例。文件名过滤器在下一节中解释。

文件名过滤器

您可以使用过滤器操作传递给适配器每个方法的文件名。过滤器是实现DotsUnited\Cabinet\Filter\FilterInterface的类。

您可以通过这种方式添加过滤器

<?php
$adapter->setFilenameFilter(new MyFilenameFilter());
?>

如果您需要多个过滤器，您可以使用DotsUnited\Cabinet\Filter\FilterChain如下所示

<?php
$filterChain = new \DotsUnited\Cabinet\Filter\FilterChain();

$filterChain->addFilter(new MyFilenameFilter1());
$filterChain->addFilter(new MyFilenameFilter2());

$adapter->setFilenameFilter($filterChain);
?>

示例

Cabinet提供了一个过滤器，可以将散列子路径添加到文件名之前，并打算与DotsUnited\Cabinet\Adapter\StreamAdapter适配器一起使用。

这将在子目录中分散文件，以确保性能，避免一个目录中有太多的文件。这是通过使用文件名MD5的可配置字符数作为目录名来实现的。这几乎可以保证均匀的分布。

只需将DotsUnited\Cabinet\Filter\HashedSubpathFilter过滤器与适配器注册

<?php
$config = array(
    'level' => 4
);

$adapter->setFilenameFilter(new \DotsUnited\Cabinet\Filter\HashedSubpathFilter($config);
?>

许可

Cabinet是在New BSD License下发布的。