Chunk Uploader Package For Laravel
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.
- PHP from 5.3.4 limits the number of concurrent uploads and by uploading a file in one request can limit the availability of a service. (max_file_uploads)
- For security reasons the payload size and the uploadable file size is limited in many systems PHP is not an exception. (upload_max_filesize)
- It can be useful to check the meta information of a file and decline an upload upfront so the user does not have to wait for minutes or seconds to upload a large file and then receive a message that the file type or mime type is not allowed.
- Can include resume functionality which means an upload can be continued after a reconnection.
However, there is not a single RFC about chunked uploads and this caused many different implementations. The most mature project at the moment is tus.
You can easily install this package using Composer, by running the following command:
composer require laracrafts/laravel-chunk-uploader
This package has the following requirements:
- PHP 7.1 or higher
- Laravel 5.5 or higher
- Register a route
Route::any('/my-route', 'MyController@myFunction');
- 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 LaraCrafts\ChunkUploader\UploadHandler;
class MyController extends Controller
{
public function myFunction(Request $request, UploadHandler $handler)
{
return $handler->handle($request);
}
}
- Resolving from the app container
use Illuminate\Http\Request;
use LaraCrafts\ChunkUploader\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 then just saving the uploaded chunks. It is also adds functionality for resumable uploads which depending on the client side library can be differ very much. Also, when possible the library gives the opportunity to download the uploaded file.
Once a file upload is finished a \LaraCrafts\ChunkUploader\Event\FileUploaded
is triggered. This event contains
the disk and the path of the uploaded file.
Registering Events & Listeners from Laravel
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
});
You can change the default driver by setting a UPLOAD_DRIVER
environment variable or publishing the
config file and changing it directly.
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 \LaraCrafts\ChunkUploader\Driver\UploadDriver
abstract class, for
which you can use the shipped drivers (e.g. \LaraCrafts\ChunkUploader\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.
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 |
Resumable.js | resumable-js |
yes | yes |
This driver is a fallback driver as it can handle normal file request. Save and delete capabilities are also added.
This driver handles requests made by the Blueimp jQuery File Upload client library.
This driver handles requests made by the DropzoneJS client library.
This driver handles requests made by the Resumable.js client library.
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 |
This identifier uses the client session and the original file name to create an identifier for the upload file.
All contributions are welcomed for this project, please refer to the CONTRIBUTING.md file for more information about contribution guidelines.
Copyright (c) 2019 LaraCrafts.
This product is licensed under the MIT license, please refer to the License file for more information.