README

Fat-Free 框架的文件抽象层

这个 F3 插件旨在提供一个简单的文件映射器，允许您为文件附加一些元信息。它包含一些文件系统适配器，为您提供对文件的统一访问，这样当您更改文件位置或文件系统时，就不需要更改代码。

这种方式，您不必担心文件将存储在哪里以及如何存储。您可以在给定的文件系统之间轻松地加载、保存和移动文件。目前可用的适配器有：本地文件系统、FTP 和 DropBox（期待更多）。

此插件需要 F3 版本 3.3.0 或更高版本。

安装

方法 1：使用 composer：composer require ikkez/f3-fal
方法 2：将 lib 文件夹的内容复制到您的 F3 lib/ 目录或其他已知于 AUTOLOADER 的目录

文件系统

FAL 包附带了一组适配器，您都可以单独使用。它们都应该实现 filesystem.php 接口，这将为您提供一个基本的文件系统操作，FAL 映射器可以从中受益。

要设置您的文件系统，请按照以下示例操作

本地文件系统适配器

挂载在您的 files/ 文件夹上

$myFS = new \FAL\LocalFS('files/');

您还可以使用这个 Prefab 快捷方式。它将创建一个映射器对象，并在 F3 UI var 中定义的布局目录上挂载 LocalFS。

$fal = \FAL::instance();

FTP 适配器

$myFS = new \FAL\FTP('html/files/','ftp.mydomain.com','user','pass');

DropBox 适配器

$myFS = new \FAL\Dropbox($appKey,$appSecret);

要访问用户的 DropBox 账户，您首先需要一个为您的应用提供的密钥和一个密钥令牌。您可以在这里免费注册一个新应用并获得密钥：https://www.dropbox.com/developers/apps

现在用户必须通过您的应用进行身份验证。因此，他将被重定向到 DropBox 身份验证页面，在那里他必须同意。要运行登录过程，请执行以下操作

$dropbox = new \FAL\Dropbox($appKey,$appSecret);
$authTokens = $dropbox->login();

如果登录成功，$authTokens 将包含一个包含 oauth_token 和 oauth_token_secret 的数组。将它们保存到用户数据旁边，并在下一次使用时通过 $dropbox->setAuthToken($token, $secret); 设置它们以重复使用该令牌对。否则，您将需要在每次请求时再次登录。(目前，令牌对也存储在浏览器 SESSION 中并重复使用。这可能在开发过程中发生变化。)

使用文件系统

$myFS->read( $file );

将返回给定文件的文本内容。其中 $file 可以始终是一个完整的文件路径（如 path/to/my/file.txt）。
$myFS->write( $file, $content );

将数据写入文件。这将覆盖现有文件。
$myFS->exists( $file );
$myFS->delete( $file );
$myFS->move( $from, $to );
$myFS->modified( $file ); 返回文件的最后修改时间戳。
$myFS->size( $file ); 返回字节数的文件大小
$myFS->isDir( $path );
$myFS->listDir( $path, $filter );

获取 $path 中所有文件和文件夹。您可以使用正则表达式模式，例如 /\.php/i 来过滤结果数组。某些文件系统还支持 $recursive 选项。
$myFS->createDir( $path );
$myFS->removeDir( $path );

某些文件系统可能具有其他功能。查看代码以了解更多信息。

使用 FAL 映射器

创建新文件

$fal = new \FAL($myFS); // pass filesystem object into constructor
// or the shortcut to your local UI dir
$fal = \FAL::instance();
$fal->load('documents/important.txt'); // use existing file, or create new if it's not existing
$fal->setContent = 'TOP SECRET DOCS CONTENT'; // write some data into the file
$fal->save(); // save the file

使用元数据

您可以为 FAL 对象添加新键。每个键都将代表一个元属性。

$fal->load('images/bridge.jpg');
$fal->title = 'a nice picture of a bridge in town';
$fal->author = 'picture was taken by: John Doe';
$fal->year = 2013;
$fal->save();

在通过 load() 方法激活映射器后，您可以简单地使用 echo $fal->title 或将其作为数组使用 echo $fal['title']。

缓存

FAL 集成了缓存功能，使用 F3 缓存引擎。这样，您可以保存慢速文件系统的远程文件，并在每次读取时无需连接和获取文件数据。

$fal->load('read/this/file.xml',3600); // cache file for 1 hour

如果您将新内容或元数据保存到已加载的缓存文件中，它也会刷新您的缓存数据。

元文件

当您保存元数据时，FAL 使用 MetaStorageInterface 进行存储。默认情况下，它使用元文件，这些文件将存储在真实文件旁边。假设您有 monalisa.jpg 并将其 artist='Leonardo da Vinci' 保存到其中。FAL 现在将创建文件 monalisa.jpg.meta，其中包含一个 json 编码的元数组。如果您希望以不同的方式命名这些元文件，可以像这样实现

// create a filesystem adapter
$localFS = new \FAL\LocalFS('files/');
// create meta file storage handler, set meta file mask
$meta = new \FAL\MetaFileStorage($localFS, '.meta_%s');
// create fal using both above
$fal = new \FAL($localFS,$meta);

现在您的元文件将看起来像 .meta_monalisa.jpg，并且由于文件名开头的点（.）而隐藏（在 Windows 上除外）。但请注意，隐藏文件。例如，当使用 FTP 适配器时，您可能需要更改 FTP 服务器设置。如果您运行 Proftpd，您的默认设置不会允许客户端查看隐藏文件，因此 FAL 找不到它们。您可以通过编辑 /etc/proftpd/proftpd.conf 并添加以下内容来更改此行为

ListOptions  "-la"

文件流

有时您可能需要处理文件。因此，FAL 创建了一个 StreamWrapper 并将文件加载到其中。现在，您可以使用此文件流来运行所有其他需要有效文件路径的常规操作。

$fal->load('data/categories.xml');
$xmlFile = $fal->getFileStream(); // fal://data/categories.xml
$xml = simplexml_load_file($xmlFile);

函数概述

$fal->load( $file, $ttl);

通过指定文件的元数据和文件内容来激活映射器。如果设置了 $ttl（以秒为单位）并且 F3 缓存开启，它还将从缓存中加载文件内容。如果缓存关闭，则在调用 getContent() 时才懒加载文件内容
$fal->delete( $file ); 删除文件和元数据
$fal->move( $from, $to ); 移动文件，并调用使用的 MetaStorage 处理器中的 move 钩子（如果存在）
$fal->getContent(); 返回文件内容。如果没有加载，将使用文件系统来读取文件
$fal->setContent( $data ); 设置文件内容
$fal->getFileStream() 注册 fal:// 流包装器，如果未定义，则将文件加载到其中并返回流路径
$fal->save( $ttl ); 如果更改了，则将新数据写入文件和元数据。如果设置了 $ttl，它还会刷新缓存记录
get(); set(); clear(); exists(); 用于处理元键字段

路线图

创建一个 DB 元存储处理程序，以摆脱元文件
添加 Google Drive 和 Amazon S3 的文件系统适配器

许可

您可以在 GNU 通用公共许可证版本 3 或更高版本下使用此插件。

ikkez / f3-fal

维护者

详细信息