README

FileStorage 是一个面向对象的PHP5文件存储抽象库。它允许您通过简单的、一致的API轻松读写任何支持的文件存储后端。如果存储后端支持，FileStorage 还支持存储元数据。

为什么选择 FileStorage？

当您使用 PHP 构建应用程序时，有许多不同的方式来存储文件。有服务器的本地文件系统，分布式系统如 GridFS 和 MogileFS，当然还有基于云的 CDN 解决方案，如 Amazon S3 等。

从应用程序的角度来看，将实现深度绑定到任何单个存储后端并不是最佳选择，因为可能需要在以后更改它。例如，您可能开始开发时使用本地文件系统，但随着应用程序的成熟可能需要切换到更高级的解决方案。这时 FileStorage 就派上用场了。使用 FileStorage 的简单 API，您可以在不更改使用它的代码的情况下更改存储后端。

特性

• 直观且非常简单的 CRUD 操作 API
• 完全兼容 PHP5，具有良好的命名空间
• 与所有支持的存储后端保持一致的行为。
• 如果存储后端支持，则支持元数据

存储后端（欢迎贡献更多，这是一个正在进行中的工作：）

• 本地文件系统
• GridFS (MongoDB)

用法

您需要做的第一件事是安装这个库并配置代码文件的自动加载。如果您可以使用 Composer 安装并且您正在使用与 PSR-0 兼容的自动加载器的框架，那么这非常简单。如果您不是，我希望您知道如何进行您的魔法操作，否则：）

当库安装完成后，您需要准备具有您应用程序特定配置的适配器，然后将适配器传递给 FileStorage 实例。最简单的示例是针对本地文件系统适配器：

use FileStorage\Adapter\Local;
use FileStorage\FileStorage;
...
$adapter = new Local("/tmp");
$storage = new FileStorage($adapter);

然后，您就准备好使用 FileStorage 了

// Initialize a new file
$file = $storage->init("myKey");

// Set some content and save
$file->setContent('foobar content');
$storage->save($file);

// Load a file from storage
$file = $storage->load("myKey");
$file->getContent();

// Delete file
$storage->delete("myKey");

就是这样简单。您只需要为您的文件选择一个键，然后就可以开始了。另一方面，当然，也有更多高级的库使用方法。请参阅下面的示例

// Load a file from storage and catch an exception if file is not found
use FileStorage\Exception\FileNotFoundException;
...
try {
    $file = $storage->load("myKey");
} catch(FileNotFoundException $e) {
	//do something
}
$file->getContent();

// Touch a new file in init and ensure that the key becomes reserved in storage
$file = $storage->init("myKey", $touch = true);

// Add some metadata if file supports it
use FileStorage\FileMetadataInterface;
...
if ($file instanceof FileMetadataInterface) {
    $file->setMetadata(array("fooMetaKey" => "barMetaValue"));
}
$storage->save($file);

选择键

FileStorage 库不会强迫您选择任何特定的键结构。您可以使用您想要的任何结构。但这里是我们的建议：

format:
context/some/identifiers/filename.extension
example:
avatars/user/12345/myavatar.jpg

这种键结构有助于您避免由于命名空间引起的键冲突，并且非常适合大多数适配器，因为斜杠在本地适配器中转换为文件夹等。

动机

首先，我想说的是FileStorage在很大程度上受到了非常棒且已经相当知名的Gaufrette库的启发，它也几乎旨在实现与FileStorage相同的目标。那么为什么要重新发明轮子呢？虽然我真的很喜欢Gaufrette的方法，并且实际上已经从它那里几乎“原封不动”地吸取了许多设计选择，但我仍然认为有些设计我真的不喜欢（可能部分是遗留问题，但仍然如此）。我甚至尝试为Gaufrette做出贡献来解决这些问题（与维护者友好合作），但由于Gaufrette已经被广泛使用，必要的改动是根本性的，这可能会导致一些不希望的BC中断。因此，我最终决定不将我的不同解决方案强加到一个已经建立的库上，而是决定自己开发一个。