README

Laravel 基于 Tus 的上传

一个用于通过 tus.io 可恢复文件上传协议在 Laravel 应用程序中处理可恢复文件上传的包。

此包包含用于控制 Tus 上传服务器的 PHP 组件和用于与服务器交互的 JavaScript 库。Tus 上传服务器是官方的 Tus 服务器二进制文件，此包不使用纯 PHP 重新实现 tus 协议。

此包目前仅在基于 Linux 的操作系统上工作。如果您想在 Windows 10 上尝试它，请考虑使用 Windows Subsystem for Linux

特性（一些处于开发中）

• 可恢复上传机制（带自分发 tusd 二进制文件）
• 上传队列处理
• JavaScript 上传组件
• 希望设置简单

安装

要开始，请通过 Composer 包管理器安装 Laravel Tus Upload。

需要 PHP >= 8.0

composer require oneofftech/laravel-tus-upload

自动注册了服务提供者 OneOffTech\TusUpload\Providers\TusUploadServiceProvider::class。

路由注册

服务提供者不会自动注册 API 路由。这是故意为之，以便有更多的自定义选项，例如使用自定义路由和控制器逻辑。

要注册路由，请在您的应用程序 RouteServiceProvider 中调用 \OneOffTech\TusUpload\Tus::routes()。

<?php

namespace App\Providers;

use OneOffTech\TusUpload\Tus;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class RouteServiceProvider extends ServiceProvider
{
    // ...

    /**
     * Define your route model bindings, pattern filters, etc.
     *
     * @return void
     */
    public function boot()
    {
        Tus::routes();

        parent::boot();
    }
}

数据库迁移

TusUpload 服务提供者将其自己的数据库迁移目录注册到框架中，因此您应该在注册服务提供者后迁移数据库。

php artisan migrate

TusUpload 迁移将创建一个用于存储上传队列的表。

现在，您可以在 User 模型中添加 HasUploads 特性，以便获取特定用户的当前上传队列。

授权上传

为了克服/防止未经授权的文件上传，上传创建端点 使用 web 守卫和网关进行保护。您可以看到 整个请求流程，以便更好地了解该过程。

名为 upload-via-tus 的网关将允许您对执行上传的用户进行深入验证。

目前，您必须定义 网关 实现。建议在 AuthServiceProvider 类的 boot 方法中定义网关。

/**
 * Register any authentication / authorization services.
 *
 * @return void
 */
public function boot()
{
    $this->registerPolicies();

    Gate::define('upload-via-tus', function ($user, $upload_request) {
        // $upload_request instanceof \OneOffTech\TusUpload\Http\Requests\CreateUploadRequest
        // ...
    });
}

回调将接收想要上传的 $user 和 CreateUploadRequest。请求可能包含根据调用者提供的自定义元数据。必需的输入是请求 id、filename，而 filesize 可能已设置，即使为 null。如果浏览器不支持 File 对象上的大小属性，则 filesize 可以为 null。此外，如果客户端已知道文件 MIME 类型，则可以发送 filetype 属性。

请求中可以发送额外的元数据。在这种情况下，一旦上传被授权，额外的字段将被保存在 TusUpload 对象的 metadata 字段中。

JavaScript 和前端

该包不提供基于 JavaScript 的交互功能，而只提供了一个执行上传的库。

该库在 public/js/tusuploader.js 中可用，并且目前需要 axios 来进行 Ajax 请求。Axios 应该在 window.axios 上可用。

关于如何正确包含 axios 的示例，您可以查看 Laravel 清洁安装后默认的 bootstrap.js 文件。

高级配置

默认情况下，该包提供一些基本默认设置，如 tusd 可执行文件的位置、上传文件夹等。

您可以通过环境变量来配置与 tus 相关的选项。

或者，如果您愿意，您可以将配置文件发布到您的 Laravel 安装中。

php artisan vendor:publish --provider="OneOffTech\TusUpload\Providers\TusUploadServiceProvider" --tag=config

如果您想自定义配置和迁移，请使用 php artisan vendor:publish --provider="OneOffTech\TusUpload\Providers\TusUploadServiceProvider"

启动 Tus 服务器

tusd 二进制文件已经包含在包的 /bin 文件夹中。二进制文件适用于 MacOS、Windows 和 Linux。包含的二进制文件已编译为 64 位架构。每个可执行文件都有一个后缀来区分操作系统版本。

要执行 Tusd 服务器，请运行 artisan tus:start 命令。

php artisan tus:start

此命令将保持监听，直到被终止。

在代理后面运行

如果您打算将请求代理到 tusd，请参阅 Can I run tusd behind a reverse proxy? 了解代理配置。

此外，请指定以下配置属性在您的 .env 文件中

TUSUPLOAD_USE_PROXY=true
TUSUPLOAD_URL=http://example.dev/tus
TUSUPLOAD_HTTP_PATH=/tus/
TUSUPLOAD_HOST=0.0.0.0

其中 http://example.dev/tus 是将要代理到 tusd 守护进程的绝对 URL。

工作原理（简要介绍）

一个 tusd 二进制文件将监听来自 JavaScript 客户端的传入上传。通过挂钩，tusd 可执行文件会调用 Laravel 应用程序来授权上传并通知上传进度。上传结束时，将触发一个事件来启用上传文件的后期处理。

有关更多信息，请参阅 docs/flow.md 和 docs/database.md。

JavaScript 库

需要记录

<script src="./public/js/tusuploader.js"></script>

var uploader = new window.TusUploader({autoUpload: true});

var input = document.getElementById('file');

input.addEventListener("change", function(e) {
    // Get the selected file from the input element
    var file = e.target.files[0]

    // add it to the uploader queue
    var addedUpload = uploader.upload(file);
});

TusUploader 对象

TusUploader 对象处理文件上传和队列管理。要创建 TusUploader 的实例，请使用构造函数。

var uploader = new window.TusUploader(options: { /*...*/ });

参数

• option: 对象:
• endpoint：库请求授权文件上传的 URL 路径
• retryDelays：在 tus 服务器未响应请求时使用的延迟数组，单位为毫秒
• autoUpload：布尔值，指示是否必须立即上传队列中添加的文件

方法

• add(file, metadata) : TusUploader.Upload 将文件添加到上传队列
• remove(id) : TusUploader.Upload[] 根据其 ID 删除文件，从队列中移除。如果已开始上传，则取消上传
• uploads(filter) : TusUploader.Upload 检索上传队列。可选地可以使用过滤器谓词进行过滤
• on(event, callback) 注册事件监听器
• off(event, callback) 注销之前注册的事件监听器

TusUploader.Upload 对象

TusUploader.Upload 对象定义了一个添加到上传队列的单个文件

属性

• id：与该上传关联的标识符
• metadata：关于上传的元数据信息，默认为文件名。一旦上传被添加到队列，它将丰富元数据
• transport：将处理实际文件上传的 TusClient 实例
• status：文件上传状态，请参阅 TusUploader.Status
• uploadToken：服务器授予的上传认证令牌
• uploadPercentage：完成百分比
• uploadSize：以字节为单位的总文件大小
• uploadTransferredSize：服务器接收的字节数
• file：添加到队列的原始 File 实例

方法

• start：开始上传
• stop：停止并取消上传

事件

• upload.queued：文件被添加到上传队列
• upload.started：队列中的文件上传已开始
• upload.progress：队列中的文件正在上传，这是最后的进度报告
• upload.completed：文件上传完成
• upload.cancelled：上传正在进行中，但已被中断
• upload.failed：文件上传失败
• upload.removed：在将文件发送到服务器之前，队列中的上传已被移除

API

需要记录

事件

与文件上传相关的事件

所有事件都有一个名为 upload 的属性，该属性包含受状态更改影响的 TusUpload 实例。

TusUploadStarted

上传已开始。在此阶段，文件尚不存在，因此只能考虑客户端发送的 filename 和可能的元数据。

TusUploadProgress

文件上传正在进行中。每次上传文件的某个块时都会触发此事件。在 TusUpload 对象上的 offset 值将给出已传输字节数的信息。

TusUploadCompleted

文件上传完成，现在可以安全访问文件内容。可以使用 TusUpload 实例上的 path() 方法检索磁盘上的路径。

TusUploadCancelled

用户取消了上传。在这种情况下，tus 服务器可能已经删除了部分上传

服务器控制事件

TusUploaderStarted

当服务器正在监听连接时触发

TusUploaderStopped

当服务器正在优雅地关闭时触发

常见问题解答 (FAQ)

可以在 Windows 上运行吗？

目前无法在 Windows 上运行带有钩子支持的 tusd，因此如果您在 Windows 上，我们鼓励您通过 Windows Subsystem for Linux 使用它

tusd 的替代启动方式

这等于默认选项的 tus:start 命令（假设从 Laravel 根目录启动）

# $PACKAGE_DIR is the directory in which the package content can be found
$PACKAGE_DIR/bin/tusd-linux --dir ./storage/app/uploads --hooks-dir $PACKAGE_DIR/hooks/linux -behind-proxy -base-path /uploads/

什么是 Tus 基础路径？

Tus 基础路径是 tusd 监听文件上传请求的端点。为了工作，它必须以 / 结尾。

我需要反向代理吗？

可能是的。tusd 通常监听与您的应用程序配置的端口不同的端口，如果您想将所有内容放在同一个端口下，您可能需要使用代理。

请参阅 Can I run tusd behind a reverse proxy? 了解更多信息。

贡献

感谢您考虑为 Laravel Tus Upload 包做出贡献！

贡献指南尚未提供，但在此期间，您仍然可以提交拉取请求。

面向开发的文档位于本仓库的 docs 文件夹下。

许可证

本项目采用 MIT 许可证，请参阅 LICENSE.txt。