README

Laravel CMS - 文件上传模块

适用于CMS的简单文件上传模块。

此模块提供简单临时文件上传功能，供其他模块使用，以允许CMS用户通过AJAX请求上传文件。

与Laravel CMS Core一起使用。

此包与Laravel 5.3和5.4兼容并经过测试。

变更日志

查看变更日志.

安装

将模块类添加到您的cms-modules.php配置文件中

    'modules' => [
        // ...
        Czim\CmsUploadModule\Modules\UploadModule::class,
    ],

将服务提供者添加到您的cms-modules.php配置文件中

    'providers' => [
        // ...
        Czim\CmsUploadModule\Providers\CmsUploadModuleServiceProvider::class,
        // ...
    ],

发布配置和迁移

php artisan vendor:publish

运行CMS迁移

php artisan cms:migrate

此模块的目的

此模块旨在帮助文件应在表单提交之前使用AJAX上传的情况。

使用CMS表单的用户快乐路径流程

1. 表单显示。
2. 用户选择要上传的文件并输入一些数据。
3. 用户提交表单。
4. 数据被存储。

然而，当表单提交后发生验证错误或其他问题时

1. 表单显示。
2. 用户选择要上传的文件并输入一些数据。
3. 用户提交表单。
4. 表单验证错误显示。
5. 用户修复数据。
6. 用户重新选择所有要上传的文件。
7. 用户提交表单。
8. 数据被存储。

上传输入被不必要地清除，迫使用户重新选择文件。

解决方案

通过异步上传文件，表单可以“记住”对这些文件的引用。

1. 表单显示。
2. 用户选择并上传文件并输入一些数据。
3. 用户提交表单。
4. 表单验证错误显示。
5. 用户修复数据。
6. 数据被存储。

此外，文件只上传一次，表单提交请求将更小，因为文件已经存储在服务器上。

这正是此模块所促进的流程。

用法

此模块没有CMS“存在”，它本身不执行任何操作。其功能可以被其他CMS模块使用。

存储文件

可以使用模块的存储路由存储文件。

向<base>/cms/fileupload/file发送一个POST请求，包含以下数据

• file（文件内容，必需）
  要存储的文件。

• name（字符串，必需）
  要存储的（原始）文件名。

• reference（字符串）
  可选的自定义引用。这并不保证是唯一的。

• validation（字符串，json）
  可选的Laravel验证规则，以JSON编码。如果提供了这些规则，文件内容将使用这些规则进行验证；如果验证失败，则不存储上传的文件，并返回验证错误消息。

别忘了包含CSRF令牌（使用Laravel接受的任何标准方式）。

服务器返回的示例成功响应

{
    "success": true,
    "id": 79,
    "reference": "REF:804747507",
    "name": "test-file.jpg",
    "size": 129059,
    "mimetype": "image/jpeg"
}

应将id值存储并用于进一步访问文件，因为它是此上传的唯一标识符。

示例错误响应

{
    "success": false,
    "error": "The file must be a file of type: txt."
}

删除文件

使用用户自己的会话上传的文件可以使用模块的删除路由进行删除。

向<base>/cms/fileupload/file/{id}发送DELETE请求。

别忘了包含CSRF令牌（使用Laravel接受的任何标准方式）。

检索文件

每个文件上传都有一个记录，可以使用FileRepository进行查找。

$repository = app(\Czim\CmsUploadModule\Contracts\Repositories\FileRepositoryInterface::class);

// Look up an upload record by ID ...
$record = $repository->findById($fileRecordId);

// ... or by a manually set reference (returns a Collection)
$records = $repository->findByReference($referenceString);

安全性

与任何模块一样，只有经过身份验证的CMS用户才能访问其路由。

此外，非管理员用户必须具有以下权限

或者简单地设置fileupload.file.*以包含上述所有内容。

会话保护

异步上传需要特别注意安全性。

除了在文件上传期间以及表单提交期间进行验证和检查之外，上传还可能被其他CMS用户劫持。

此模块提供了一个SessionGuard类来帮助防止这种情况。默认情况下已启用：每个上传都将与用户的会话相关联。

然而，请注意，自定义调用，如通过FileRepository访问记录，不受保护。必须手动调用SessionGuard进行检查

$guard = app(\Czim\CmsUploadModule\Contracts\Support\Security\SessionGuardInterface::class);

if ( ! $guard->check($fileRecordId)) {
    throw new \Exception('Not your file!');
}

可以通过将配置密钥cms-upload-module.upload.restrict.session设置为false来禁用会话保护。

这些基本的安全措施之外的措施，如将上传与（CMS）特定用户关联，不是开箱即用的。如果需要，应在您的应用程序或CMS模块中实现。

检查模块是否可用

当编写使用此上传模块的CMS模块时，建议创建回退行为，以防上传模块不可用。

要检查此模块是否可用，您可以询问核心模块管理器

/** @var Czim\CmsCore\Contracts\Modules\ModuleManagerInterface $moduleManager */
$moduleManager = app(\Czim\CmsCore\Support\Enums\Component::MODULES);

if ($moduleManager->has('file-uploader')) {
    // The file upload module is available...
}

示例

有关此模块使用的示例，请参阅模型模块。

它具有用于Stapler文件和图像上传的表单显示策略，以及一个存储策略，如果已加载，则使用上传模块。

垃圾回收

未使用的上传文件可能会使您的应用程序变得杂乱无章。

为了防止这种情况，默认启用自动垃圾回收功能。这通过抽签方式工作（每个文件上传有1%的概率进行清理），清理将删除一天之前的文件（但这个时间是可以配置的）。

还有一个Artisan命令可以执行清理操作

php artisan cms:upload:cleanup

贡献

请参阅贡献指南以获取详细信息。

鸣谢

• 所有贡献者

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。