README

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

要求 PHP >= 5.6.0

简介

PHP 连接器提供了一种灵活的方式，用于管理不同存储类型的文件。默认支持两种存储方式：

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

下面详细描述每种存储的配置细节。您可以按照需要实现任何其他存储类型的实现，只需实现 API 和 Storage 类。

安装

composer require servocoder/richfilemanager-php

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

AWS PHP SDK

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

{
  "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 默认提供入口点脚本，因此您无需从头创建。在本节中，您可以找到设置入口脚本的说明和示例。

启动应用程序。

$app = new \RFM\Application();

创建并设置存储类实例。通常您将使用单个存储，但您可以为多种存储类型创建实例，以便在 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);

创建并设置 API 类实例。与存储实例不同，您只能设置一个 API 实例。

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

或者

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

运行应用程序。

$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 文件内容。

用户存储文件夹访问

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

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

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

session_start();

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

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

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 权限
必须根据 patterns 和 extensions 配置选项允许 $filepath

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 权限
必须根据 patterns 和 extensions 配置选项允许 $filepath
必须将 read_only 配置选项设置为 false，否则所有写入操作都将被禁用

指定用户存储文件夹

本地存储文件夹

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

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 方法参数如下

文件夹的相对或绝对路径（请参阅下面的示例）
是否在不存在时创建文件夹
与 "serverRoot" 配置选项相同

本地存储文件夹设置示例

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

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

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

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

设置配置选项

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

使用 setRoot 方法（另一种方式）

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

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

设置配置选项

    "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

这可能会在与 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 方法参数如下

存储桶下 "文件夹" 的相对路径
如果不存在是否创建文件夹

调试和日志记录

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

版本 <= 1.08

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

要启用记录器，将 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

版本 >= 1.0.9

RichFilemanager 现在支持 Monolog。

您可以使用尽可能多的 Monolog 处理器

$config = [
    'logger' => [
        'enabled' => true,
        'handlers' => [
            new \Monolog\Handler\RotatingFileHandler($filename, 7, \Monolog\Logger::INFO)        
        ],
    ],
];

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

如果（并且仅当）提供了 file 选项，它将被转换为 Monolog\Handler\StreamHandler

MIT 许可证

在 MIT 许可证下发布。

izapbrasil / richfilemanager-php

维护者

详细信息