tus php

其他类别 • 2025-08-25

tusphp

使用tus可重新上传的上传协议v1.0.0在PHP中重新上传PHP中载



中文⚡laravel＆Lumen集成⚡Symfony Integration⚡CAKEPHP集成⚡WordPress Integration

TUS是基于HTTP的协议，用于重新启动文件上传。可重新启动意味着您可以在不上传的情况下继续在没有重新上传的情况下继续前进的位置。如果用户想暂停，或者在网络发行或服务器中断时，可能会愿意发生中断。

目录

  • 安装
  • 用法
    • 服务器
      • nginx
      • apache
    • 客户
    • 第三方客户库
    • 云提供商
  • 扩展支持
    • 到期
    • 级联
  • 事件
    • 回应事件
  • 中间件
    • 创建中间件
    • 添加中间件
    • 跳过中间件
  • 在本地设置开发环境和/或运行示例
    • Docker
  • 贡献
  • 关于这个项目的问题？
  • 支持者

安装

通过作曲家拉包装。 

$ composer require ankitpokhrel/tus-php

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

$ composer require ankitpokhrel/tus-php:^1.2

用法
基本的TUS架构

服务器

这就是简单的服务器的样子。 

 // server.php

// Either redis, file or apcu. Leave empty for file based cache.
$ server   = new  TusPhp  Tus  Server ( ' redis ' );
$ 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

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

 TusPhp Config:: set ( '  ' );

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

或者，您可以在服务器中设置REDIS_HOST ， REDIS_PORT和REDIS_DB env，以覆盖服务器和客户端的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.your*s**ite.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的内置文件系统功能，因此，如果其API支持在附加二进制模式下写作，我们可以轻松地将其上传到诸如Amazon S3之类的提供商。直接将文件上传到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事件用于这些操作。在不同执行点，服务器派遣以下事件。

事件名称 派遣
tus-server.upload.created 在POST请求期间创建上传之后。
tus-server.upload.progress 在PATCH请求期间上传块后。
tus-server.upload.complete 上传完成并进行校验和验证后。
tus-server.upload.merged 在串联请求期间合并了所有部分上传之后。

回应事件

要收听事件，您只需将侦听器附加到事件名称即可。创建了一个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接口。手柄方法提供了请求和响应对象供您操纵。 

 

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);

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

可以在examples/文件夹中找到基于AJAX的示例。您可以如下所述使用Docker构建并运行它。

Docker

确保系统中安装了Docker和Docker-Compose。然后，从项目root运行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.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。

关于这个项目的问题？

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

下载源码

通过命令行克隆项目:

git clone https://github.com/ankitpokhrel/tus-php.git

相关文章

aimeos base

2025-08-25

hprose php

2025-08-25

avatar

2025-08-25

php qrcode

2025-08-25

推荐阅读

向上：银河游戏免安装正式版

2026-01-23

风暴驭使正式中文版

2026-01-23

冥河：贪婪之刃中文试玩版

2026-01-23

超级键盘侠免安装绿色中文版

2026-01-23