search

coding-socks / laravel-upload-handler

Chunk Uploader Package For Laravel
MIT License
11 stars 4 forks source link

readme

Laravel Upload Handler

Upload Handler Package For Laravel

Github Actions Badge Downloads Badge Version Badge Coverage Badge License Badge

This package helps integrate a Laravel application with chunk uploader libraries eg. DropzoneJS and jQuery-File-Upload from blueimp.

Uploading a large file in chunks can help reduce risks.

However, there is not a single RFC about chunked uploads and this caused many implementations. The most mature project at the moment is tus.

Similar projects:

Table of contents

Installation

You can easily install this package using Composer, by running the following command:

composer require coding-socks/laravel-upload-handler

Requirements

This package has the following requirements:

Caret Version Range (^)

Usage

  1. Register a route 
    Route::any('/my-route', 'MyController@myFunction');
  2. Retrieve the upload handler. (The chunk upload handler can be retrieved from the container in two ways.)
    • Using dependency injection 
      
use Illuminate\Http\Request;
use CodingSocks\UploadHandler\UploadHandler;

class MyController extends Controller { public function myFunction(Request $request, UploadHandler $handler) { return $handler->handle($request); } }

  - Resolving from the app container
```php
use Illuminate\Http\Request;
use CodingSocks\UploadHandler\UploadHandler;

class MyController extends Controller
{
    public function myFunction(Request $request)
    {
        $handler = app()->make(UploadHandler::class);
        return $handler->handle($request);
    }
}

The handler exposes the following methods:

Method Description
handle Handle the given request

"Handle" is quite vague but there is a reason for that. This library tries to provide more functionality than just saving the uploaded chunks. It is also adds functionality for resumable uploads which depending on the client side library can differ very much.

Events

Once a file upload finished a \CodingSocks\UploadHandler\Event\FileUploaded is triggered. This event contains the disk and the path of the uploaded file.

You can also add a Closure as the second parameter of the handle method to add an inline listener. The listener is called with the disk and the path of the uploaded file.

$handler->handle($request, function ($disk, $path) {
    // Triggered when upload is finished
});

Changing the driver

You can change the default driver by setting an UPLOAD_DRIVER environment variable or publishing the config file and changing it directly.

Adding your own drivers

Much like Laravel's core components, you can add your own drivers for this package. You can do this by adding the following code to a service provider.

app()->make(UploadManager::class)->extend('my_driver', function () {
    return new MyCustomUploadDriver();
});

If you are adding a driver you need to extend the \CodingSocks\UploadHandler\Driver\BaseHandler abstract class, for which you can use the shipped drivers (e.g. \CodingSocks\UploadHandler\Driver\BlueimpUploadDriver) as an example as to how.

If you wrote a custom driver that others might find useful, please consider adding it to the package via a pull request.

Drivers

Below is a list of available drivers along with their individual specs:

Service Driver name Chunk upload Resumable
Monolith monolith no no
Blueimp blueimp yes yes
DropzoneJS dropzone yes no
Flow.js flow-js yes yes
ng-file-upload ng-file-upload yes no
Plupload plupload yes no
Resumable.js resumable-js yes yes
simple-uploader.js simple-uploader-js yes yes

Monolith driver

This driver is a fallback driver as it can handle normal file request. Save and delete capabilities are also added.

Blueimp driver

website

This driver handles requests made by the Blueimp jQuery File Upload client library.

DropzoneJS driver

website

This driver handles requests made by the DropzoneJS client library.

Flow.js driver

website

This driver handles requests made by the Flow.js client library.

Because of Issue #44 you must use forceChunkSize option.

ng-file-upload driver

website

This driver handles requests made by the ng-file-upload client library.

Plupload driver

website

This driver handles requests made by the Plupload client library.

Resumable.js driver

website

This driver handles requests made by the Resumable.js client library.

Because of Issue #44 you must use forceChunkSize option.

simple-uploader.js driver

website

This driver handles requests made by the simple-uploader.js client library.

Because of Issue #44 you must use forceChunkSize option.

Identifiers

In some cases an identifier is needed for the uploaded file when the client side library does not provide one. This identifier is important for resumable uploads as the library has to be able to check the status of the given file for a specific client. Without the identifier collisions can happen.

Service Driver name
Session identifier session
Auth identifier auth
NOP identifier nop

Session identifier

This identifier uses the client session and the original file name to create an identifier for the upload file.

Auth identifier

This identifier uses the id of the authenticated user and the original file name to create an identifier for the upload file.

It will throw UnauthorizedException when the user is unauthorized. However, it is still recommended using the auth middleware.

NOP identifier

This identifier uses the original file name to create an identifier for the upload file. This does not abstract the file identifier which can be useful for testing.

Contribution

All contributions are welcomed for this project, please refer to the CONTRIBUTING.md file for more information about contribution guidelines.

License

This product is licensed under the MIT license, please refer to the License file for more information.