README

此软件包是 RichFilemanager 项目的一部分。

需要 PHP >= 5.6.4

简介

PHP 连接器提供了一种灵活的方式来管理不同存储类型的文件。开箱即支持两种存储类型：

• 本地文件系统存储
• AWS S3 存储

每种存储类型的配置细节如下。你可以通过实现 Api 和 Storage 类来创建任何其他你希望使用的存储实现。

安装

composer require servocoder/richfilemanager-php

注意：你可能不需要单独安装 PHP 连接器。运行主软件包的 composer 即可。请参阅 PHP 连接器 安装指南。

AWS PHP SDK

如果你打算使用 AWS S3 存储，请确保在 RichFilemanager 的 composer.json 文件的 "require" 部分中添加了版本 >= 3.18.0 的 AWS PHP SDK 软件包。

{
  "require": {
    "servocoder/richfilemanager-php": "*",
    "aws/aws-sdk-php": "^3.18.0"
  }
}

相关信息 - Amazon PHP SDK 安装指南：https://docs.aws.amazon.com/aws-sdk-php/v3/guide/getting-started/installation.html

入口点设置

RichFilemanager 提供了 入口点脚本，因此你无需从头开始创建它。在本节中，你可以找到有关设置入口脚本的说明和示例。

1. 启动应用程序。

$app = new \RFM\Application();

1. 创建并设置存储类实例。通常你将使用单个存储，但你可以为各种存储启动实例并在 API 中使用它们。例如，AWS S3 API 可以使用 S3 存储实例来管理原始文件，并使用本地存储来管理图片缩略图。更多详细信息请参阅 配置 部分。

// local filesystem storage
$local = new \RFM\Repository\Local\Storage();
$app->setStorage($local);

// AWS S3 storage instance
$s3 = new \RFM\Repository\S3\Storage();
$app->setStorage($s3);

1. 创建并设置 API 类实例。与存储实例不同，你可以设置一个 API 实例。

// local filesystem API
$app->api = new RFM\Api\LocalApi();

或者

// AWS S3 API
$app->api = new RFM\Api\AwsS3Api();

1. 运行应用程序。

$app->run();

配置

配置文件包含在软件包中，但你可以在创建存储实例时轻松重定义任何选项。为此，你必须将选项数组传递给存储类构造函数。请参阅下面的示例。

本地文件系统存储

请参阅 配置文件 选项。文件中的每个选项都有详细的注释，且在此文章中不会重复。

覆盖配置文件中默认选项的示例

$config = [
    'security' => [
        'readOnly' => true,
        'extensions' => [
            'policy' => 'ALLOW_LIST',
            'restrictions' => [
                'jpg',
                'jpe',
                'jpeg',
                'gif',
                'png',
                'html',
            ],
        ],
    ],
];

$local = new \RFM\Repository\Local\Storage($config);

AWS S3 存储

请参阅 配置文件 选项。

AWS S3 存储的大部分配置选项与本地文件系统存储相同，并来自 config.local.php 文件。

请注意，根据默认配置，图片缩略图将与其他文件一起存储在 AWS S3 存储中。此示例演示了如何更改此行为并将缩略图存储在本地存储的 "s3_thumbs" 目录中

$config_s3 = [
    'images' => [
        'thumbnail' => [
            'dir' => 's3_thumbs',
            'useLocalStorage' => true,
        ],
    ],
    'credentials' => [
        'region' => 'your region',
        'bucket' => 'your aws s3 bucket',
        'credentials' => [
            'key' => 'your aws s3 key',
            'secret' => 'your aws s3 secret',
        ],
        'defaultAcl' => \RFM\Repository\S3\StorageHelper::ACL_PUBLIC_READ,
        'debug' => false,
    ],
];

$s3 = new \RFM\Repository\S3\Storage($config_s3);

安全

由于 RichFilemanager 能够操作服务器上的文件，因此有必要安全地保护你的应用程序。

配置文件 的 security 部分定义了选项，这些选项在安全方面提供了广泛的定制。仔细学习注释以了解每个选项的用法。

服务器脚本执行

默认情况下，所有服务器脚本的执行在默认的userfiles文件夹中都被禁用。请参阅.htaccess和IIS文件的内容。

用户存储文件夹访问

默认情况下，任何人都可以访问用户存储文件夹。为了使您的应用程序更安全，入口脚本提供了一些预定义的函数，允许您定义自己的认证机制。

1. fm_authenticate() - 验证用户，例如检查密码登录，或限制客户端IP地址。如果函数返回false，则用户将看到错误。您可以将它改为将用户重定向到登录页面。

此函数在每次服务器连接时都会被调用。它必须返回true。

session_start();

function fm_authenticate()
{
    return $_SESSION['user_type'] === "admin";
}

注意：此函数仅授权用户连接和/或加载初始页面。对单个文件或目录的授权由下面的函数提供。

1. fm_has_read_permission() - 执行自定义单个文件的读取权限检查。

在文件系统读取操作之前会调用此函数，其中$filepath是要读取的文件或目录的绝对路径。它必须返回true，否则读取操作将被拒绝。

function fm_has_read_permission($filepath)
{
    if ($filepath === "/var/www/userfiles/some_file.txt") {
        return false;    
    }
    
    return true;
}

注意：这不是唯一必须通过的权限检查。读取操作还必须通过以下权限检查

• 文件系统权限（如果有），例如Linux上的POSIX rwx权限
• $filepath必须根据patterns和extensions配置选项允许访问

1. fm_has_write_permission() - 执行自定义单个文件的写入权限检查。

在文件系统写入操作之前会调用此函数，其中$filepath是要写入的文件或目录的绝对路径。它必须返回true，否则写入操作将被拒绝。

function fm_has_write_permission($filepath)
{
    if ($filepath === "/var/www/userfiles/some_file.txt") {
        return false;    
    }
    
    return true;
}

注意：这不是唯一必须通过的权限检查。写入操作还必须通过

• 文件系统权限（如果有），例如Linux上的POSIX rwx权限
• $filepath必须根据patterns和extensions配置选项允许访问
• read_only配置选项必须设置为false，否则所有写入都将被禁用

指定用户存储文件夹

本地存储文件夹

有两个配置选项会影响用户文件存储文件夹的位置

serverRoot (bool)
fileRoot (bool|string)

通过组合这些选项的值，您可以更改存储文件夹的目标位置。

serverRoot - 默认为"true"，表示存储文件夹位置是相对于服务器文档根文件夹定义的。如果用户文件的存储文件夹位于服务器根文件夹之外，则将值设置为"false"。如果fileRoot选项设置为"false"，则忽略serverRoot的值 - 总是"true"。

fileRoot - 默认为"false"，表示存储文件夹位于服务器文档根文件夹下，命名为"userfiles"。您可以通过以下规则使用以下值代替"false"值来指定用户文件存储文件夹的特定路径

• 如果serverRoot设置为"false"，则为绝对路径，例如"/var/www/html/filemanager/userfiles/"
• 如果serverRoot设置为"true"，则为相对路径，例如"/filemanager/userfiles/"

您可以通过以下两种方式在配置部分更改选项值

1. 在配置存储实例时

$config = [
    "options" => [
        "serverRoot" => true,
        "fileRoot" => false,
    ],
];

$local = new \RFM\Repository\Local\Storage($config);

2. 使用"setRoot"存储方法

$local = new \RFM\Repository\Local\Storage();

$local->setRoot('user_folder', true, true);

setRoot方法参数如下

1. 文件夹的相对或绝对路径（请参阅以下示例）
2. 是否在不存在的情况下创建文件夹
3. 与"serverRoot"配置选项相同

本地存储文件夹设置示例

1. 默认情况 - 用户文件夹位于RichFilemanager根文件夹内

默认用户文件夹命名为 "userfiles"，位于 RichFilemanager 根文件夹内。应用部署后应自动检测 "userfiles" 文件夹位置，因此无需在配置选项中进行任何更改，默认配置如下

    "serverRoot" => true,
    "fileRoot" => false,

1. 指定位于服务器文档根文件夹下的用户文件夹

• 设置配置选项

    "serverRoot" => true,
    "fileRoot" => "/filemanager/files/", // relative path to a storage folder of user files

• 使用 setRoot 方法（备选方法）

    $local->setRoot("/filemanager/files/", true, true);

1. 指定位于服务器文档根文件夹外的用户文件夹

• 设置配置选项

    "serverRoot" => false,
    "fileRoot" => "/var/www/html/filemanager/files/", // absolute server path

• 使用 setRoot 方法（备选方法）

    $local->setRoot("/var/www/html/filemanager/files/", true, false);

重要：如果用户文件存储文件夹位于服务器文档根文件夹外，则应用无法定义用户文件的绝对URL。RichFilemanager 仍可预览文件，但通过读取连接器URL而不是使用绝对URL。

这意味着预览URL将类似于

http://mydomain.com/my_project/filemanager/connectors/php/filemanager.php?mode=readfile&path=/image.jpg

而不是绝对直接URL

http://mydomain.com/my_project/filemanager/files/image.jpg

这可能会导致 RichFilemanager 与所见即所得（WYSIWYG）编辑器的集成出现问题。

幸运的是，在大多数情况下，可以显式指定访问存储文件夹的URL。请参阅 处理预览URL RichFilemanager 维基文章以获取详细信息。

基于会话设置动态用户文件夹

此示例展示了如何根据会话变量动态设置存储文件夹路径。

session_start();

// supposed that user folder name is stored in "userfolder" session variable
$folderPath = "/filemanager/files/" . $_SESSION["userfolder"];

$app = new \RFM\Application();

$local = new \RFM\Repository\Local\Storage();

// set relative path to storage root folder
$local->setRoot($folderPath, true);

$app->setStorage($local);

// set application API
$app->api = new RFM\Api\LocalApi();

$app->run();

AWS S3 存储文件夹

由于 AWS S3 存储根文件夹依赖于您的 S3 存储桶配置，您只能更改存储桶下的用户文件夹。使用 "setRoot" 存储方法

$s3 = new \RFM\Repository\S3\Storage();

$s3->setRoot('user_folder', true);

setRoot方法参数如下

1. 存储桶下 "folder" 的相对路径。
2. 如果不存在，是否创建文件夹

调试和日志记录

如果您在使用 RichFilemanager 时遇到任何问题，您可能想查看发生了什么。

所有日志都存储在您的本地文件系统中，因此您必须配置您的 本地文件系统存储

要启用记录器，请将 logger.enabled 选项设置为 true，您还可以使用 logger.file 选项指定日志文件的完整路径

$config = [
    'logger' => [
        'enabled' => true,
        'file' => '/var/log/filemanager.log',
    ],
];

$local = new \RFM\Repository\Local\Storage($config);

请注意，默认情况下，日志记录是禁用的，并且日志文件位置由 sys_get_temp_dir() PHP 函数定义

• Linux: /tmp/filemanager.log
• Windows 7: C:\Users\%username%\AppData\Local\Temp\filemanager.log

MIT 许可证

在 MIT 许可证 下发布。