DEV Community

Cover image for Resumable file upload in PHP: Handle large file uploads in an elegant way
Konsole
Konsole

Posted on • Edited on • Originally published at hackernoon.com

Resumable file upload in PHP: Handle large file uploads in an elegant way

#php #opensource #showdev #webdev

Ever struggled with large file upload in PHP? Wondered if you could continue uploading where you left off without re-uploading whole data again in case of any interruptions? If this sounds familiar to you, then keep reading.

File upload is a common task we do in almost all of our modern web projects. With all different tools available, it is not that hard to implement file upload feature in any language. But, still, when it comes to large file upload things gets a bit complicated.

Say, you are trying to upload a fairly large file. You have been waiting for more than an hour already and the upload is at 90%. Then suddenly, your connection drops or browser crashed. The upload is aborted and you need to start from the beginning. Frustrating, isn't it? Even worse, if you are in a slow connection, like many places in the world, no matter how often you try you will only be able to upload first part of the upload every time.

Basic TUS architecture

In this post, we will see an attempt to solve this problem in PHP by uploading files in resumable chunks using tus protocol.

What is tus?

Tus is a HTTP based open protocol for resumable file uploads. Resumable means we can carry on where we 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.

Tus protocol was adopted by Vimeo in May 2017.

Why tus?

Quoting from Vimeo's blog:

We decided to use tus in our upload stack because the tus protocol standardizes the process of uploading files in a concise and open manner. This standardization will allow API developers to focus more on their application-specific code, and less on the upload process itself.

Another main benefit of uploading a file this way is that you can start uploading from a laptop and even continue uploading the same file from your mobile or any other device. This is a great way to enhance your user experience.

Basic Tus Architecture

Basic Tus Architecture

Getting Started

Let's start by adding our dependency.



$ composer require ankitpokhrel/tus-php
Enter fullscreen mode Exit fullscreen mode

tus-php is a framework agnostic pure PHP server and client implementation for the tus resumable upload protocol v1.0.0.

GitHub logo ankitpokhrel / tus-php

🚀 A pure PHP server and client for the tus resumable upload protocol v1.0.0

TusPHP

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

Resumable file upload in PHP using tus resumable upload protocol v1.0.0

TusPHP Demo

Medium Article ⚡ Laravel & Lumen Integration ⚡ Symfony Integration ⚡ CakePHP Integration ⚡ WordPress Integration

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.

Table of Contents

Installation

Pull the package via composer.

$ composer require ankitpokhrel/tus-php
// Use v1 for php7.1, Symfony 3 or 4.
…
Enter fullscreen mode Exit fullscreen mode
View on GitHub

Update: Vimeo is now using TusPHP in v3 of their Official PHP library for the Vimeo API.

Creating a server to handle our requests

This is how a simple server looks like.



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

$response = $server->serve();

$response->send();

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

You need to configure your server to respond to a specific endpoint. For example, in Nginx, you would do something like this:



# nginx.conf

location /files {
    try_files $uri $uri/ /path/to/server.php?$query_string;
}
Enter fullscreen mode Exit fullscreen mode

Let's assume that the URL to our server is http://server.tus.local. So, based on above nginx configuration we can access our tus endpoints using http://server.tus.local/files.

Now, we have following RESTful endpoints available to work with.



# Gather information about server's current configuration
OPTIONS /files

# Check if the given upload is valid
HEAD /files/{upload-key}

# Create a new upload
POST /files

# Resume upload created with POST
PATCH /files/{upload-key}

# Delete the previous upload
DELETE /files/{upload-key}
Enter fullscreen mode Exit fullscreen mode

Check out the protocol details for more info about the endpoints.

If you are using any frameworks like Laravel, instead of modifying your server config, you can define routes to all tus based endpoints in your framework route file. We will cover this in detail in another tutorial.

Handling upload using tus-php client

Once the server is in place, the client can be used to upload a file in chunks. Let us start by creating a simple HTML form to get input from the user.



<form action="upload.php" method="post" enctype="multipart/form-data">
    <input type="file" name="tus_file" id="tus-file" />
    <input type="submit" value="Upload" />
</form>
Enter fullscreen mode Exit fullscreen mode

After a form is submitted, we need to follow few steps to handle the upload.

1. Create a tus-php client object 



// Tus client
$client = new \TusPhp\Tus\Client('http://server.tus.local');
Enter fullscreen mode Exit fullscreen mode

The first parameter in the above code is your tus server endpoint.

2. Initialize client with file metadata

To keep an upload unique, we need to use some identifier to recognize the upload in upcoming requests. For this, we will have to generate a unique upload key which can be used to resume the upload later. You can either explicitly provide an upload key or let the system generate a key by itself.



// Set upload key and file meta
$client->setKey($uploadKey)
    ->file($_FILES['tus_file']['tmp_name'], 'your file name');
Enter fullscreen mode Exit fullscreen mode

If you don't provide upload key explicitly, above step will be something like this:



$client->file($_FILES['tus_file']['tmp_name'], 'your file name');

$uploadKey = $client->getKey(); // Unique upload key
Enter fullscreen mode Exit fullscreen mode

3. Upload a chunk 



// $chunkSize is size in bytes, i.e. 5000000 for 5 MB
$bytesUploaded = $client->upload($chunkSize);
Enter fullscreen mode Exit fullscreen mode

Next time, when you want to upload another chunk you can use same upload key to continue.



// To resume upload in next request
$bytesUploaded = $client->setKey($uploadKey)->upload($chunkSize);
Enter fullscreen mode Exit fullscreen mode

Once the upload is complete, the server verifies upload against the checksum to make sure the uploaded file is not corrupt. The server will use sha256 algorithm by default to verify the upload.

The full implementation of the demo video above can be found here.

Handling upload using tus-js-client

Uppy is a sleek, modular file uploader plugin developed by same folks behind tus protocol. You can use uppy to seamlessly integrate official tus-js-client with a tus-php server. That means we are using php implementation of a server and js implementation of a client.



uppy.use(Tus, {
  endpoint: 'https://server.tus.local/files/', // your tus endpoint
  resume: true,
  autoRetry: true,
  retryDelays: [0, 1000, 3000, 5000]
})
Enter fullscreen mode Exit fullscreen mode

Check out more details in uppy docs and example implementation here.

Partial Uploads

The tus-php Server supports concatenation extension and is capable of concatenating multiple uploads into a single one enabling clients to perform parallel uploads and to upload non-contiguous chunks.

The full example of partial uploads can be found here.

Final Words

The tus-php project itself is still in its initial stage. Some sections might change in the future. Three different implementation examples can be found in the example folder. Feel free to try and report any issues found. Pull requests and project recommendations are more than welcome.

Happy Coding!

Top comments (3)

Collapse
 
ohffs profile image
ohffs •

Last time I looked at Tus you couldn't control the filename on the server-side - is it still like that? I was looking to replace using Minio with it - but not being able to control the filenames/dirs was a bit of an issue :-/

Collapse
 
konsole profile image
Konsole •

Hi @ohffs ,

Thank you for trying the package.

If you are using both tus-php client and server you can provide file name in client itself. For eg:

$client->setKey($uploadKey)->file('/path/to/file', 'my-awesome-file.mp4');

If you want to do it in server side you can do it using hooks which is coming soon in new version: github.com/ankitpokhrel/tus-php/pu...

$server->event()->addListener(
    'tus-server.upload.complete',
     function (\TusPhp\Events\TusEvent $event) {
        // Perform post upload operation.
        // For instance, renaming a file in your case
    });

Hope that address your issue. Feel free to open issue in case you need any help.

Collapse
 
ohffs profile image
ohffs •

Oh - thanks for that! Sadly I'd be using the Golang server (embedded device so no PHP) - but I see now it has hooks too so I might be able work something out :-). Thanks for the tip! :-D

Read next

ivanivanovv profile image

Stripe Subscription Integration in Node.js [2024 Ultimate Guide]

Ivan Ivanov -

nikl profile image

Running a JAX Program from Dart Using C++ FFI

Nik L. -

bhaidar profile image

Safe Database Migration: Converting MySQL Enum to String in Laravel

Bilal Haidar -

dotnetfullstackdev profile image

Experimental attribute in C# is a powerful tool : Let's explore

DotNet Full Stack Dev -