Repository files navigation

A package for handling resumable file uploads in a Laravel application via thetus.io resumable file upload protocol.

This package contains a PHP component for controlling the Tus upload server and a javascript library for interacting with the server. The Tus upload server is the officialTus server binary, this package does not re-implement the tus protocol in pure PHP.

This package currently works only on Linux based OS. If you want to try it on Windows 10, please takeinto consideration to use theWindows Subsystem for Linux

• Resumable upload mechanism (with self distributed tusd binary)
• Upload queue handling
• Javascript Upload component
• Hopefully easy setup

To get started, install Laravel Tus Upload via theComposer package manager.

Requires PHP >= 8.0

composer require oneofftech/laravel-tus-upload

TheOneOffTech\TusUpload\Providers\TusUploadServiceProvider::class service provider is auto-registered.

Routes registration

The API routes are not registered automatically by the service provider. This is done on purpose to have more customization options, for example the usage of custom routes and controller logic.

To register the routes call\OneOffTech\TusUpload\Tus::routes() from within your applicationRouteServiceProvider

<?phpnamespaceApp\Providers;useOneOffTech\TusUpload\Tus;useIlluminate\Foundation\Support\Providers\AuthServiceProviderasServiceProvider;class RouteServiceProviderextends ServiceProvider{// .../**     * Define your route model bindings, pattern filters, etc.     *     * @return void     */publicfunctionboot()    {        Tus::routes();parent::boot();    }}

Database migrations

The TusUpload service provider registers its own database migration directory with the framework, soyou should migrate your database after registering the provider.

php artisan migrate

The TusUpload migrations will create atable to store the uploads queue.

In yourUser model you can, now, add theHasUploads trait in order to grab the current uploadqueue for a specific user.

Authorizing an upload

To overcome/prevent an un-authorized file upload theupload creation endpoint is protected with theweb guard and a gate. You see theoverall request flow for a better view on how theprocess works.

The Gate, namedupload-via-tus, will let you verify deeply the upload action against the user thatis performing it.

Currently you must define thegate implementation.The suggested location where the Gate can be defined is it in theboot method of theAuthServiceProvider class:

/** * Register any authentication / authorization services. * * @return void */publicfunctionboot(){$this->registerPolicies();    Gate::define('upload-via-tus',function ($user,$upload_request) {// $upload_request instanceof \OneOffTech\TusUpload\Http\Requests\CreateUploadRequest// ...    });}

The callback will receive the$user that wants to do the upload and theCreateUploadRequest. The request mightcontain custom metadata, according to the caller. Required inputs are the requestid, thefilename, whilefilesizemight be set, even if null. Thefilesize can be null if the browser don't support the size property on the File object.In addition thefiletype attribute can be sent, if the file mime type is already known to client.

Additional metadata can be sent in the request. In this case the additional fields will be saved inthemetadata field on theTusUpload object once the upload is authorized.

Javascript and the frontend

The package don't provide fancy Javascript based interactions, but only a library to perform the uploads.

The library is available inpublic/js/tusuploader.js and currently requireaxios,to make Ajax requests. Axios should be available onwindow.axios.

For an example on how to properly include axios you might want to take a look at the defaultbootstrap.jsfile available in Laravel after a clean install.

Out of the box the package has some base defaults, like the location of thetusd executable, the upload folder and so on.

You can configure the tus related options via environment variables:

In alternative, if you prefer, you can publish the configuration file in your Laravel installation.

php artisan vendor:publish --provider="OneOffTech\TusUpload\Providers\TusUploadServiceProvider" --tag=config

If you want to customize both configuration and migrations usephp artisan vendor:publish --provider="OneOffTech\TusUpload\Providers\TusUploadServiceProvider"

The tusd binary is already included in the package under the/bin folder.The binaries are available for MacOS, Windows and Linux. The included binaries have been compiled for 64 bit architecture. Each executable has a suffix to distinguish between the OS version.

To execute the Tusd server launch the artisantus:start command.

php artisan tus:start

This command will keep listening until killed.

If you are going to proxy requests to tusd, please refer toCan I run tusd behind a reverse proxy? for the proxy configuration.

In addition please specify the following configuration attributes in your.env file:

TUSUPLOAD_USE_PROXY=trueTUSUPLOAD_URL=http://example.dev/tusTUSUPLOAD_HTTP_PATH=/tus/TUSUPLOAD_HOST=0.0.0.0

wherehttp://example.dev/tus is the absolute URL that the will be proxied to the tusd deamon.

Atusd binary will listen for incoming uploads, sent by the javascript client. Viahooks the tusd executable calls the Laravel application to authorize the upload and to inform about the uploadprogress. At the end of the upload an event will be triggered to enable post-processing of the uploaded file.

For more information please refer todocs/flow.md anddocs/database.md.

to be documented

<scriptsrc="./public/js/tusuploader.js"></script>

varuploader=newwindow.TusUploader({autoUpload:true});varinput=document.getElementById('file');input.addEventListener("change",function(e){// Get the selected file from the input elementvarfile=e.target.files[0]// add it to the uploader queuevaraddedUpload=uploader.upload(file);});

TheTusUploader object handles file upload and queue management. To create an instance of theTusUploader usethe constructor function.

varuploader=newwindow.TusUploader(options:{/*...*/});

arguments

• option: Object:
• endpoint: the URL path to which the library calls for authorizing a file upload
• retryDelays: the array of delays, in milliseconds, that will be used in case the tus server is not replying to requests
• autoUpload: a boolean indicating whenever the file added to the queue must be uploaded immediately

methods

• add(file, metadata) : TusUploader.Upload adds a file to the upload queue
• remove(id) : TusUploader.Upload[] remove a file, given its id, from the queue. It cancel the upload if already in progress
• uploads(filter) : TusUploader.Upload retrieve the upload queue. Optionally can be filtered using the filter predicate
• on(event, callback) register an event listener
• off(event, callback) unregister a previously registered event listener

TheTusUploader.Upload object define a single file added to the queue of the uploads

properties

• id: the identifier associated to this upload
• metadata: the metadata information about the upload, by default the filename. It is enriched with the metadata added once the upload has been added to the queue
• transport: the instance of the TusClient that will handle the real file upload
• status: the file upload status, see TusUploader.Status
• uploadToken: the upload authentication token granted by the server
• uploadPercentage: the completion percentage
• uploadSize: the total file size in bytes
• uploadTransferredSize: the bytes received by the server
• file: the original File instance added to the queue

methods

• start: start the upload
• stop: stop and cancel the upload

• upload.queued a File was added to the upload queue
• upload.started a File upload, in the queue, was started
• upload.progress a File in the queue is being uploaded and this is the last progress report
• upload.completed a File upload completed
• upload.cancelled: upload was in progress, but has been interruped
• upload.failed: a File upload failed
• upload.removed: a queued upload has been removed before sending the file to the server

to be documented

All events have a single property calledupload that contains the instance oftheTusUpload being subject of the status change.

The upload is started. At this stage the file don't exists yet and is safe to only consider thefilenameand eventual metadata sent by the client.

The file upload is in progress. This event is triggered everytime a chunk of the file is uploaded. Theoffset value on the theTusUpload object will give the information on how many bytes havebeen transferred.

The file upload completed and is now safe to access the file content. The path on disk can beretrieved with thepath() method on theTusUpload instance.

The user cancelled the upload. At this point the tus server might have already deleted the partial upload

Triggered when the server is listening for connections

Triggered when the server is being shutdown gracefully

Currently running tusd on Windows with the hook support is not possible, therefore if you areon Windows we encourage to use it through theWindows Subsystem for Linux

tusd, the alternative start

This is equal to thetus:start command with default options (assuming the start from the Laravel root folder)

# $PACKAGE_DIR is the directory in which the package content can be found$PACKAGE_DIR/bin/tusd-linux --dir ./storage/app/uploads --hooks-dir$PACKAGE_DIR/hooks/linux -behind-proxy -base-path /uploads/

Tus base-path is the endpoint where tusd listen for file upload requests. To work it must end with/.

Probably yes. Tusd usually listen on a different port than the one configured for your application, if you want to haveeverything under the same port, you might want to use a proxy.

Please refer toCan I run tusd behind a reverse proxy? forfurther explanation.

Thank you for considering contributing to the Laravel Tus Upload package!

The contribution guide is not available yet, but in the meantime you can still submit Pull Requests.

Development oriented documentation is located under thedocs folder in this repository.

This project is licensed under the MIT license, seeLICENSE.txt.