diff --git a/README.md b/README.md index 9162d1c..5361b31 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,29 @@ Chunk Uploader Package For Laravel -

- - - - - -

+[![](https://travis-ci.org/LaraCrafts/laravel-chunk-uploader.svg?branch=master)](https://travis-ci.org/LaraCrafts/laravel-chunk-uploader) +[![](https://poser.pugx.org/laracrafts/laravel-chunk-uploader/downloads)](https://packagist.org/packages/laracrafts/laravel-chunk-uploader) +[![](https://poser.pugx.org/laracrafts/laravel-chunk-uploader/version)](https://packagist.org/packages/laracrafts/laravel-chunk-uploader) +[![](https://scrutinizer-ci.com/g/LaraCrafts/laravel-chunk-uploader/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/LaraCrafts/laravel-chunk-uploader/) +[![](https://poser.pugx.org/laracrafts/laravel-chunk-uploader/license)](https://packagist.org/packages/laracrafts/laravel-chunk-uploader) + +This package helps integrate a Laravel application with chunk uploader libraries eg. +[DropzoneJS](https://www.dropzonejs.com/) and +[jQuery-File-Upload from blueimp](https://blueimp.github.io/jQuery-File-Upload/). + +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][php-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][php-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](https://tus.io/). - [Installation](#installation) - [Requirements](#requirements) @@ -37,15 +53,21 @@ composer require laracrafts/laravel-chunk-uploader This package has the following requirements: -- PHP 7.0 or higher +- PHP 7.1 or higher - Laravel 5.5 or higher ## Usage -The chunk upload handler can be retrieved from the container in two ways: - -- Using dependency injection +1. Register a route +```php +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 ```php +use Illuminate\Http\Request; +use LaraCrafts\ChunkUploader\UploadHandler; + class MyController extends Controller { public function myFunction(Request $request, UploadHandler $handler) @@ -54,26 +76,46 @@ class MyController extends Controller } } ``` -- Resolving from the app container + - Resolving from the app container ```php -$handler = app()->make(UploadHandler::class) -$handler->handle($request); +use Illuminate\Http\Request; +use LaraCrafts\ChunkUploader\UploadHandler; + +class MyController extends Controller +{ + public function myFunction(Request $request) + { + $handler = app()->make(UploadHandler::class); + $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. + ### Events 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](https://laravel.com/docs/5.8/events#registering-events-and-listeners) 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. +```php +$handler->handle($request, function ($disk, $path) { + // Triggered when upload is finished +}); +``` + ### Changing the driver You can change the default driver by setting a `UPLOAD_DRIVER` environment variable or publishing the @@ -81,8 +123,8 @@ config file and changing it directly. ### Adding your own drivers -Much like Laravels [core components][5], you can add your own drivers for this package. You can do this -by adding the following code to a central place in your application (preferably a service provider). +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. ```php app()->make(UploadManager::class)->extend('my_driver', function () { @@ -90,11 +132,11 @@ app()->make(UploadManager::class)->extend('my_driver', function () { }); ``` -If you are adding a driver you need to extend the `UploadDriver.php` abstract class, for which -you can use the shipped drivers (e.g. `MonolithUploadDriver`) as an example as to how. +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. +If you wrote a custom driver that others might find useful, please consider adding it to the package via a pull request. ## Drivers @@ -138,14 +180,16 @@ This identifier uses the client session and the original file name to create an ## Contribution -All contributions are welcomed for this project, please refer to the [CONTRIBUTING.md][1] file for more information about contribution guidelines. +All contributions are welcomed for this project, please refer to the [CONTRIBUTING.md][contributing] file for more +information about contribution guidelines. ## License **Copyright (c) 2019 LaraCrafts.** -This product is licensed under the MIT license, please refer to the [License file][2] for more information. +This product is licensed under the MIT license, please refer to the [License file][license] for more information. -[1]: https://github.com/LaraCrafts/laravel-chunk-uploader/blob/master/CONTRIBUTING.md -[2]: https://github.com/LaraCrafts/laravel-chunk-uploader/blob/master/LICENSE -[5]: https://laravel.com/docs/5.0/extending#managers-and-factories +[contributing]: https://github.com/LaraCrafts/laravel-chunk-uploader/blob/master/CONTRIBUTING.md +[license]: https://github.com/LaraCrafts/laravel-chunk-uploader/blob/master/LICENSE +[php-max-file-uploads]: https://www.php.net/manual/en/ini.core.php#ini.max-file-uploads +[php-upload-max-filesize]: https://www.php.net/manual/en/ini.core.php#ini.upload-max-filesize