ragulara93/tus-php

tus-php 的分支

维护者

详细信息

github.com/ragulara93/tus-php

源代码

资助包维护！
paypal.me/ankitpokhrel

安装次数: 4,490

依赖者: 0

建议者: 0

安全性: 0

星标: 0

关注者: 0

分支: 203

3.1 2021-09-23 15:23 UTC

Requires

Requires (Dev)

MIT ea09c77b7c333437dd0b4a4f0833d2cb1439eb50

  • Ragu <ragulara93.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-23 22:21:14 UTC

README

PHP Version Build Status Code Coverage Scrutinizer Code Quality Downloads Software License

使用 tus resumable upload protocol v1.0.0 在 PHP 中实现可断点续传的文件上传

TusPHP Demo

Medium 文章 ⚡ Laravel & Lumen 集成 ⚡ Symfony 集成 ⚡ CakePHP 集成 ⚡ WordPress 集成

tus 是一种基于 HTTP 的可断点续传文件上传协议。可断点续传意味着在发生中断的情况下，您可以继续上传而无需重新上传整个数据。中断可能是用户有意识地暂停上传，也可能是由于网络问题或服务器故障等意外情况。

目录

安装

使用 composer 拉取此包。

$ composer require ankitpokhrel/tus-php

// Use v1 for php7.1, Symfony 3 or 4.

$ composer require ankitpokhrel/tus-php:^1.2

使用方法

服务器

这是一个简单服务器的样子。

// server.php

$server   = new \TusPhp\Tus\Server('redis'); // Either redis, file or apcu. Leave empty for file based cache.
$response = $server->serve();

$response->send();

exit(0); // Exit from current PHP process.

您需要重写服务器以响应对特定端点的请求。例如

Nginx
# nginx.conf

location /files {
    try_files $uri $uri/ /server.php?$query_string;
}

自 nginx 1.7.11 版本起，新增了新的配置选项 fastcgi_request_buffering。当启用缓冲时，在将请求发送到 FastCGI 服务器之前，将从客户端读取整个请求体。禁用此选项可能有助于解决上传过程中的超时问题。此外，如果您在系统 tmp 分区的磁盘空间不足时，这也有助于解决问题。

如果您不关闭 fastcgi_request_buffering 并使用 fastcgi，则无法继续上传，因为 nginx 不会在文件完全上传之前将请求返回给 PHP。

location ~ \.php$ {
    # ...

    fastcgi_request_buffering off; # Disable request buffering
    
    # ...
}

可以在 这里 找到示例 nginx 配置。

Apache
# .htaccess

RewriteEngine on

RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^files/?(.*)?$ /server.php?$1 [QSA,L]

默认最大上传大小为 0，表示没有限制。您可以根据以下说明设置最大上传大小。

$server->setMaxUploadSize(100000000); // 100 MB in bytes

服务器和客户端的默认 redis 和文件配置可以在 config/server.php 和 config/client.php 中找到。要覆盖默认配置，您可以简单地将其复制到您希望的位置并更新参数。然后您需要在执行任何其他操作之前设置配置。

\TusPhp\Config::set('<path to your config>');

$server = new \TusPhp\Tus\Server('redis');

或者，您可以在服务器上设置 REDIS_HOST、REDIS_PORT 和 REDIS_DB 环境变量来覆盖服务器和客户端的 redis 设置。

客户端

客户端可用于创建、继续和/或删除上传。

$client = new \TusPhp\Tus\Client($baseUrl);

// Key is mandatory.
$key = 'your unique key';

$client->setKey($key)->file('/path/to/file', 'filename.ext');

// Create and upload a chunk of 1MB
$bytesUploaded = $client->upload(1000000);

// Resume, $bytesUploaded = 2MB
$bytesUploaded = $client->upload(1000000);

// To upload whole file, skip length param
$client->file('/path/to/file', 'filename.ext')->upload();

要检查文件之前是否已部分上传，您可以使用 getOffset 方法。如果没有上传或无效，它返回 false，否则返回已上传的总字节数。

$offset = $client->getOffset(); // 2000000 bytes or 2MB

从缓存中删除部分上传。

$client->delete($key);

默认情况下，客户端使用 /files 作为API路径。您可以通过 setApiPath 方法来更改它。

$client->setApiPath('/api');

默认情况下，服务器将使用 sha256 算法来验证上传的完整性。如果您想使用不同的哈希算法，可以通过使用 setChecksumAlgorithm 方法来实现。要获取支持的哈希算法列表，可以向服务器发送 OPTIONS 请求。

$client->setChecksumAlgorithm('crc32');

第三方客户端库

Uppy

Uppy 是一个由 tus 协议背后的团队开发的时尚、模块化的文件上传插件。您可以使用 Uppy 无缝集成官方 tus-js-client 和 tus-php 服务器。更多详细信息请参阅 uppy 文档。

uppy.use(Tus, {
  endpoint: 'https://tus-server.yoursite.com/files/', // use your tus endpoint here
  resume: true,
  autoRetry: true,
  retryDelays: [0, 1000, 3000, 5000]
})
Tus-JS-Client

Tus-php 服务器与官方 tus-js-client JavaScript 库兼容。

var upload = new tus.Upload(file, {
  endpoint: "/tus",
  retryDelays: [0, 3000, 5000, 10000, 20000],
  metadata: {
    name: file.name,
    type: file.type
  }
})
upload.start()

云服务提供商

许多云服务提供商实现了 PHP streamWrapper 接口，使我们能够使用内置的 PHP 函数从这些服务提供商存储和检索数据。由于 tus-php 依赖于 PHP 内置的文件系统函数，因此我们可以轻松地使用它将文件上传到像 Amazon S3 这样的服务提供商，如果它们的 API 支持以追加二进制模式写入。以下是将文件直接上传到 S3 桶的示例实现

// server.php
// composer require aws/aws-sdk-php

use Aws\S3\S3Client;
use TusPhp\Tus\Server;
use Aws\Credentials\Credentials;

$awsAccessKey = 'AWS_ACCESS_KEY'; // YOUR AWS ACCESS KEY
$awsSecretKey = 'AWS_SECRET_KEY'; // YOUR AWS SECRET KEY
$awsRegion    = 'eu-west-1';      // YOUR AWS BUCKET REGION
$basePath     = 's3://your-bucket-name';

$s3Client = new S3Client([
    'version' => 'latest',
    'region' => $awsRegion,
    'credentials' => new Credentials($awsAccessKey, $awsSecretKey)
]);
$s3Client->registerStreamWrapper();

$server = new Server('file');
$server->setUploadDir($basePath);

$response = $server->serve();
$response->send();

exit(0);

扩展支持

  • 创建扩展主要已经实现，用于创建上传。目前无法延迟上传的长度。
  • 终止扩展已实现，用于终止完成和未完成的上传，使服务器能够释放使用的资源。
  • 校验和扩展已实现，服务器将默认使用 sha256 算法来验证上传。
  • 过期扩展已实现，详情如下。
  • 此连接扩展已实现，但服务器无法处理未完成的连接。

过期

服务器能够删除已过期但未完成的上传。您可以使用以下命令手动或作为 cron 作业来删除它们。请注意，此命令检查您的缓存存储以查找过期的上传。因此，请确保在缓存过期之前运行它，否则它将无法找到所有需要清除的文件。

$ ./vendor/bin/tus tus:expired --help

Usage:
  tus:expired [<cache-adapter>] [options]

Arguments:
  cache-adapter         Cache adapter to use: redis, file or apcu [default: "file"]

Options:
  -c, --config=CONFIG   File to get config parameters from.

eg:

$ ./vendor/bin/tus tus:expired redis

Cleaning server resources
=========================

1. Deleted 1535888128_35094.jpg from /var/www/uploads

您可以使用 --config 选项覆盖默认的 redis 或文件配置。

$ ./vendor/bin/tus tus:expired redis --config=<path to your config file>

连接

服务器能够将多个上传合并为一个，使客户端能够执行并行上传并将非连续块上传。

// Actual file key
$uploadKey = uniqid();

$client->setKey($uploadKey)->file('/path/to/file', 'chunk_a.ext');

// Upload 10000 bytes starting from 1000 bytes
$bytesUploaded = $client->seek(1000)->upload(10000);
$chunkAkey     = $client->getKey();

// Upload 1000 bytes starting from 0 bytes
$bytesUploaded = $client->setFileName('chunk_b.ext')->seek(0)->upload(1000);
$chunkBkey     = $client->getKey();

// Upload remaining bytes starting from 11000 bytes (10000 +  1000)
$bytesUploaded = $client->setFileName('chunk_c.ext')->seek(11000)->upload();
$chunkCkey     = $client->getKey();

// Concatenate partial uploads
$client->setFileName('actual_file.ext')->concat($uploadKey, $chunkBkey, $chunkAkey, $chunkCkey);

此外，服务器将验证校验和与合并的文件，以确保文件未损坏。

事件

通常，您可能希望在上传完成后或创建后执行某些操作。例如，您可能希望在上传后裁剪图像或转码文件并发送给您的用户。您可以使用 tus 事件来执行这些操作。以下事件在执行的不同点由服务器发出。

响应事件

要监听事件，您可以简单地将监听器附加到事件名称。创建并传递给所有监听器的 TusEvent 实例。

$server->event()->addListener('tus-server.upload.complete', function (\TusPhp\Events\TusEvent $event) {
    $fileMeta = $event->getFile()->details();
    $request  = $event->getRequest();
    $response = $event->getResponse();

    // ...
});

或者，您还可以绑定自定义类的某些方法。

/**
 * Listener can be method from any normal class.
 */
class SomeClass
{
    public function postUploadOperation(\TusPhp\Events\TusEvent $event)
    {
        // ...
    }
}

$listener = new SomeClass();

$server->event()->addListener('tus-server.upload.complete', [$listener, 'postUploadOperation']);

中间件

您可以使用中间件来操纵服务器的请求和响应。中间件可以用于在服务器调用实际处理方法之前运行一段代码。您可以使用中间件进行身份验证、处理 CORS、白名单/黑名单 IP 等。

创建中间件

为了创建中间件，您需要实现 TusMiddleware 接口。处理方法为您提供了请求和响应对象以便操作。

<?php

namespace Your\Namespace;

use TusPhp\Request;
use TusPhp\Response;
use TusPhp\Middleware\TusMiddleware;

class Authenticated implements TusMiddleware
{
    // ...

    /**
     * {@inheritDoc}
     */
    public function handle(Request $request, Response $response)
    {
        // Check if user is authenticated
        if (! $this->user->isLoggedIn()) {
            throw new UnauthorizedHttpException('User not authenticated');
        }

        $request->getRequest()->headers->set('Authorization', 'Bearer ' . $this->user->token());
    }

    // ...
}

添加中间件

要添加中间件，从服务器获取中间件对象，并简单地传递中间件类。

$server->middleware()->add(Authenticated::class, AnotherMiddleware::class);

或者，您也可以传递中间件类对象。

$authenticated = new Your\Namespace\Authenticated(new User());

$server->middleware()->add($authenticated);

跳过中间件

如果您希望跳过或忽略任何中间件，可以使用 skip 方法。

$server->middleware()->skip(Cors::class, AnotherMiddleware::class);

设置开发环境和/或本地运行示例

本实现的基于Ajax的示例可以在examples/文件夹中找到。您可以使用以下描述构建和运行它。

Docker

请确保您的系统中已安装docker和docker-compose。然后，从项目根目录运行docker脚本。

# PHP7
$ make dev

# PHP8
$ make dev8

# or, without make

# PHP7
$ bin/docker.sh

# PHP8
$ PHP_VERSION=8 bin/docker.sh

现在，客户端可以通过http://0.0.0.0:8080访问，服务器可以通过http://0.0.0.0:8081访问。默认API端点设置为/files，上传的文件可以在uploads文件夹中找到。所有docker配置都可以在docker/文件夹中找到。

如果您想从新开始，可以使用以下命令。它将删除并重新创建所有容器、镜像和上传文件夹。

# PHP7
$ make dev-fresh

# PHP8
$ make dev8-fresh

# or, without make

# PHP7
$ bin/clean.sh && bin/docker.sh

# PHP8
$ bin/clean.sh && PHP_VERSION=8 bin/docker.sh

我们还提供了一些实用脚本，可以简化您的本地开发体验。有关所有可用命令的列表，请参阅Makefile。如果您不使用make，则可以使用此处提供的shell脚本。

贡献

  1. 如果您尚未安装，请安装PHPUnit和composer。
  2. 安装依赖关系
    $ make vendor

# or

$ composer install
  3. 使用phpunit运行测试
    $ make test

# or

$ composer test

# or

$ ./vendor/bin/phpunit
  4. 将更改与PSR2编码标准进行验证
    # fix lint issues
$ make lint

# dry run
$ make lint-dry

您可以使用xdebug enable和xdebug disable在容器内启用和禁用Xdebug。

关于此项目的疑问？

请随时报告您发现的任何错误。拉取请求、问题和项目建议都非常欢迎！

支持者

JET BRAINS