README

使用 PHP 通过 tus 可恢复上传协议 v1.0.0 实现可恢复文件上传。

tus 是一种基于 HTTP 的可恢复文件上传协议。可恢复意味着在出现任何中断的情况下，您可以继续上传而无需重新上传全部数据。中断可能是由用户自愿暂停导致的，也可能是由于网络问题或服务器中断导致的意外情况。

thunder tus 是目前最可靠的 PHP tus 协议实现。它针对 高并发（实际场景）和集成简单性而设计，没有外部依赖（复杂的缓存引擎等）。它还符合 PSR-7 标准，以便将 tus 协议带到现代 PHP 框架，如 Slim 3。

扩展：基于 tus 协议的可扩展性功能，thunder tus 还包括两个新的扩展

• CrossCheck：上传文件的最终校验和，以确保最大的可靠性；
• Express：通过单个 HTTP 调用来进行 tus 上传——使 tus 更适合移动环境和其他以性能为优先的环境。

安装

通过 composer 获取此包。

$ composer require TCB13/thunder-tus-php

基本用法

使用 composer 安装 tcb13/thunder-tus-php 和以下示例中使用的其他包

$ composer require tcb13/thunder-tus-php psr/http-message zendframework/zend-diactoros zendframework/zend-httphandlerrunner

创建您的 tus-server.php 文件

<?php
include "vendor/autoload.php";

$request = Zend\Diactoros\ServerRequestFactory::fromGlobals();
$response = new Zend\Diactoros\Response();

$backend = new FileSystem(__DIR__ . DIRECTORY_SEPARATOR . "uploads");
$server = new ThunderTUS\Server($request, $response);
$server->setStorageBackend($backend);
$server->setApiPath("/");
$server->handle();
$response = $server->getResponse();

$emitter = new Zend\HttpHandlerRunner\Emitter\SapiEmitter();
$emitter->emit($response);

在您的虚拟主机中创建以下 .htaccess（或等效文件）

RewriteEngine on
RewriteBase /
RewriteRule ^(.*)$ tus-server.php [L,QSA]

现在您可以使用位于 examples/client-express.php 的 TUS 客户端上传文件。上传完成后，您可以在另一个脚本中通过调用

$finalStorageDirectory = "/var/www/html/uploads";
$server = new ThunderTUS\Server();
$status = $server->completeAndFetch($filename, $finalStorageDirectory);
if (!$status) {
      throw new \Exception("Could not fetch ({$filename}) from storage backend: not found.");
}

文件将从临时存储后端移动到 $finalStorageDirectory 目录。

您也可以使用 ThunderTUS\Server::completeAndStream() 将最终文件作为流检索，或者使用 ThunderTUS\Server::complete() 保持与临时部分相同的位置。

存储后端

为了使用 ThunderTUS，您必须选择一个存储后端。这些后端用于在上传完成前临时存储上传的部分。存储后端有多种选择，从本地文件系统到 MongoDB 的 GridFS。

• FileSystem：一个简单易用的后端，适用于简单的项目，它将上传的部分追加到其构造函数提供的路径上的文件中；
• Amazon S3：在分布式场景中很有用（例如，您的后端从多个位于负载均衡器后面的机器上提供服务），是 Amazon S3 协议的实现。已测试与 DigitalOcean 的 Spaces 的兼容性；
• Redis：也适用于分布式场景，将上传的部分存储在 Redis 数据库中；
• MongoDB：也适用于分布式场景，将上传的部分存储在 MongoDB GridFS 存储桶中。

您还可以通过扩展 StorageBackend 类和/或实现 StorageInterface 接口来创建自己的存储后端。

S3 存储后端

$server  = new \ThunderTUS\Server($request, $response);

$client = new S3Client([
    "version"     => "latest",
    "region"      => "...",
    "endpoint"    => "...",
    "credentials" => [
        "key"    => "--key--",
        "secret" => "--secret---",
    ],
]);
$backend  = new S3($client, "your-bucket", "optional-path-prefix");
$server->setStorageBackend($backend);

$server->setUploadMaxFileSize(50000);
$server->setApiPath("/tus");
$server->handle();

您可以在基本用法部分中描述的方式检索上述完成的上传。

MongoDB 存储后端

// Connect to your MongDB
$con = new \MongoDB\Client($configs->uri, $configs->options]);
$mongodb= $con->selectDatabase($configs->db]);

// Start ThunderTUS
$server  = new \ThunderTUS\Server($request, $response);

// Load the MongoDB backend
$mongoBackend = new MongoDB($mongodb);
$server->setStorageBackend($mongoBackend );

// Set other settings and process requests
$server->setUploadMaxFileSize(50000);
$server->setApiPath("/tus");
$server->handle();

// Send the response back to the client
$response = $server->getResponse();

您可以在基本用法部分中描述的方式检索上述完成的上传。

Redis 存储后端

$server  = new \ThunderTUS\Server($request, $response);

$redisBackend = new Redis($redisClient);
$server->setStorageBackend($redisBackend);

$server->setUploadMaxFileSize(50000);
$server->setApiPath("/tus");
$server->handle();

您可以在基本用法部分中描述的方式检索上述完成的上传。

ThunderTUS & 依赖注入

ThunderTUS 被设计为可以集成到依赖注入系统/容器中。在简单场景中，您应该将 PSR HTTP 请求和响应的实现传递给 ThunderTUS 的构造函数，但这不是必需的。有时可能希望能够在 Service Provider 中实例化 Server，稍后在一个控制器中提供 PSR HTTP 实现。

示例：ThunderTUS服务提供商

public static function register()
{
    $settings = $this->container->get("settings.tusProtocol");

    // Create the server
    $server = new Server(); // No request or response implementations passed here

    // Load the filesystem Backend
    $backend = new FileSystem($settings->path]);
    $server->setStorageBackend($backend);

    // Set TUS upload parameters
    $server->setUploadMaxFileSize((int)$settings->maxSize);
    $server->setApiPath($settings->endpoint);
    
    return $server;
}

现在我们来处理上传的控制器

public function upload()
{
    // Resolve TUS using the container
    /** @var \ThunderTUS\Server $server */
    $server = $this->container->get(\ThunderTUS\Server::class);

    // Load the request or response implementations here!
    $server->loadHTTPInterfaces($this->request, $this->response); 

    // Handle the upload request
    $server->handle();

    // Send the response back to the client
    return $server->getResponse();
}

我们通过调用 $server->loadHTTPInterfaces(..) 只在控制器上提供了PSR HTTP请求和响应的实现。

客户端实现

• PHP客户端：在examples目录中，您可以找到一个简单的客户端以及tus-crosscheck / tus-express的示例；
• JavaScript / ES6：https://github.com/stenas/thunder-tus-js-client - 一个设计精良、实现出色的tus-crosscheck / tus-express客户端，占位空间最小。