https://github.com/tcb13/thunder-tus-php
PHP implementation of the TUS resumable upload protocol v1.0.0.
https://github.com/tcb13/thunder-tus-php
file-transfer high-concurrency large-files php resumable-upload tus tus-protocol
Last synced: about 1 month ago
JSON representation
PHP implementation of the TUS resumable upload protocol v1.0.0.
- Host: GitHub
- URL: https://github.com/tcb13/thunder-tus-php
- Owner: TCB13
- License: mit
- Created: 2018-12-16T22:58:26.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2019-11-11T11:43:35.000Z (over 5 years ago)
- Last Synced: 2025-04-22T20:15:12.191Z (about 1 month ago)
- Topics: file-transfer, high-concurrency, large-files, php, resumable-upload, tus, tus-protocol
- Language: PHP
- Homepage:
- Size: 3.13 MB
- Stars: 12
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
README
# ThunderTUS PHP
Resumable file upload in PHP using tus resumable upload protocol v1.0.0.
**tus** is a HTTP based protocol for resumable file uploads. Resumable means you can carry on where you left off without re-uploading whole data again in case of any interruptions. An interruption may happen willingly if the user wants to pause, or by accident in case of a network issue or server outage.
**thunder tus** is the most reliable implementation of the tus protocol for PHP yet. Designed for **high concurrency** (real world scenarios) and integration simplicity it's **free of external dependencies** (complex caching engines etc.). It is also **PSR-7 compliant** in order to bring the tus protocol to modern PHP frameworks such as **Slim 3**.
**extensions**: building on the extensibility capabilities of the tus protocol, thunder tus also includes two new extensions:
- **CrossCheck**: final checksum of the uploaded files to ensure maximum reliability;
- **Express**: tus uploads with a single HTTP call - making tus better suited for mobile contexts and other environments where performance is a priority.
## Installation
Pull the package via composer.
```shell
$ composer require TCB13/thunder-tus-php
```
## Basic Usage
Use composer to install `tcb13/thunder-tus-php` and some other packages used in the following examples:
```shell
$ composer require tcb13/thunder-tus-php psr/http-message zendframework/zend-diactoros zendframework/zend-httphandlerrunner
```
Create your `tus-server.php` file:
````php
setStorageBackend($backend);
$server->setApiPath("/");
$server->handle();
$response = $server->getResponse();
$emitter = new Zend\HttpHandlerRunner\Emitter\SapiEmitter();
$emitter->emit($response);
````
Create the following `.htaccess` (or equivalent) at your virtual host:
````
RewriteEngine on
RewriteBase /
RewriteRule ^(.*)$ tus-server.php [L,QSA]
````
Now you can go ahead and upload a file using the TUS client included at `examples/client-express.php`.
After the upload is finished you may retrieve the file in another script by calling:
````php
$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.");
}
````
The file will be moved from the temporary storage backend to the `$finalStorageDirectory` directory.
You may also retrieve the final file as a stream with `ThunderTUS\Server::completeAndStream()` or keep on the same place as the temporary parts with `ThunderTUS\Server::complete()`
## Storage Backends
In order to use **ThunderTUS you must pick a storage backend**. Those are used to temporally store the uploaded parts until the upload is completed. Storage backends come in a variety of flavours from the local filesystem to MongoBD's GridFS:
- `FileSystem`: a quick to use and understand backend for simple projects that will append uploaded parts into a file stored at the path provided on it's constructor;
- `Amazon S3`: useful in distributed scenarios (eg. your backend serves requests from multiple machines behind a load balancer), an implementation of Amazon's S3 protocol. Tested compatibility with DigitalOcean's Spaces;
- `Redis`: also for distributed scenarios, stores uploaded parts into a Redis database;
- `MongoDB`: also for distributed scenarios, will store uploaded parts inside a MongoDB GridFS bucket.
You may also implement your own storage backend by extending the `StorageBackend` class and/or implementing the `StorageInterface` interface.
### S3 Storage Backend
````php
$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();
`````
You may later retrieve the finished upload as described above at the basic usage section.
### MongoDB Storage Backend
````php
// 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();
````
You may later retrieve the finished upload as described above at the basic usage section.
### Redis Storage Backend
````php
$server = new \ThunderTUS\Server($request, $response);
$redisBackend = new Redis($redisClient);
$server->setStorageBackend($redisBackend);
$server->setUploadMaxFileSize(50000);
$server->setApiPath("/tus");
$server->handle();
`````
You may later retrieve the finished upload as described above at the basic usage section.
## ThunderTUS & Dependency Injection
ThunderTUS was designed to be integrated into dependency injection systems / containers.
In simple scenarios you should pass an implementation of a PSR HTTP request and response to ThunderTUS's constructor, however this is optional. Sometimes it might be desirable to be able to instantiate the `Server` in a Service Provider and provide the PSR HTTP implementations later in a controller.
Example of a **ThunderTUS service provider**:
````php
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;
}
````
Now the **controller that handles uploads**:
````php
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();
}
````
We've only provided the PSR HTTP request and response implementations on the controller by calling `$server->loadHTTPInterfaces(..)`.
## Client Implementations
- **PHP Client**: At the `examples` directory you may find a simple client and tus-crosscheck / tus-express examples as well;
- **JavaScript / ES6**: https://github.com/stenas/thunder-tus-js-client - a very well designed and implemented tus-crosscheck / tus-express capable client with minimal footprint.