README

Uploader is a package that provides a simple interface to upload image and document assets to your website in a consistent manner.

Install

Via Composer

$ composer require browner12/uploader

Setup

Add the service provider to the providers array in config/app.php.

'providers' => [
    browner12\uploader\UploaderServiceProvider::class,
];

Publishing

You can publish everything at once

php artisan vendor:publish --provider="browner12\uploader\UploaderServiceProvider"

or you can publish groups individually.

php artisan vendor:publish --provider="browner12\uploader\UploaderServiceProvider" --tag="config"

Configuration

Setting up your new uploader.php configuration file is very important to the uploader behaving as you expect. Each option is well documented in the file, but we will also address them here, due to their integral role.

First off we have the base_directory. This is where all of your uploads will be stored, relative to your resource root (most likely the public directory). While you may choose to leave this option blank, one benefit to having a directory for all user generated content is it is easy to add to your .gitignore, and it is easier to transfer if needed.

'base_directory' => '',

Next we have the original_directory, optimized_directory, and thumbnail_directory. When you upload an image, by default, the package will automatically create optimized and thumbnail versions of the file, which can drastically help improve page loads. With these options, you can set the name of the directory each goes into.

'original_directory' => 'original',
'optimized_directory' => '',
'thumbnail_directory' => 'thumbnail',

Next you can set if you want optimized images and thumbnails to be automatically created when you upload an image. By default, they are turned on because this can aid in drastically reducing your bandwidth usage and load times.

'create_optimized' => true,
'create_thumbnails' => true,

Next you will set the default extensions and mime types for each type of upload. We include some sensible defaults.

'document_extensions' => ['pdf', 'doc', 'docx', 'ppt'],
'image_extensions' => ['jpg', 'jpeg', 'gif', 'png'],
'video_extensions' => ['avi', 'mov', 'mp4', 'ogg'],
'audio_extensions' => ['mp3', 'wav'],

'document_mime_types_' => ['application/pdf', 'application/msword'], //other defaults omitted for brevity
'image_mime_types_' => ['image/gif', 'image/jpeg', 'image/png'],
'video_mime_types_' => ['video/avi', 'video/quicktime', 'video/mp4', 'video/ogg'],
'audio_mime_types_' => [ 'audio/mpeg', 'audio/mpeg3', 'audio/wav'],

The maximum upload size is the largest file size (in bytes) you will accept for an upload. Remember that if this value is larger than the maximum upload size of your server, it could result in errors.

'maximum_upload_size' => 32000000,

When you upload images, and an optimized image is created, two properties will affect the optimized image. First, you can set the quality of the new image to a value between 1 and 100. You may also set a maximum width of the optimized image. This can be helpful to keep the file size down as well, because simply changing the quality of a very large image, is still going to result in a very large file size. If you do not wish to constrain the width, set the value to 0.

'optimized_image_quality' => 60,
'optimized_maximum_width' => 1000,

Lastly, you can set the width of the generated thumbnails.

'thumbnail_width' => 100,

Usage

Start by manually instantiating the uploader

$uploader = new Uploader();

or using dependency injection.

public function __construct(UploaderInterface $uploader)
{
    $this->uploader = $uploader;
}

There are four main methods with the uploader, each for uploading a different type of file.

$this->uploader->document($file, $path, $filename);
$this->uploader->image($file, $path, $filename);
$this->uploader->video($file, $path, $filename);
$this->uploader->audio($file, $path, $filename);

One important thing to note is that $file must be an instance of \Symfony\Component\HttpFoundation\File\UploadedFile. If you are using Laravel, all files will be passed as this object automatically. The $path you pass will be relative to your base_directory defined in your configuration. If you omit the $filename, the original name of the file will be used. If you choose this option please be aware that files with the same name will be overwritten. Please also note that irregular file names may cause unexpected issues. We may choose to address this in a future version of the package.

Let's look at an example of how to best use the uploader inside of a Laravel controller.

public function store(Request $request)
{
    try{

        if($request->hasFile('image')){
            
            $file = $this->uploader->image($request->file('image'), 'dogs', 1);
        }
    }
    catch(browner12\uploader\UploaderException $e){
    
        //handle any errors here
    }
    
    var_dump($file);
}

Notice the uploader also returns information to you. The $file will be an array with information similar to the following:

array(9) {
    ["id"] => string(7) "1.jpg"
    ["name"] => string(11) "1.jpg"
    ["size"] => int(97065)
    ["mime_type"] => string(10) "image/jpeg"
    ["extension"] => string(3) "jpg"
    ["original_name"] => string(7) "1.jpg"
    ["url"] => string(34) "content/image/original/1.jpg"
    ["optimized_url"] => string(14) "content/image/1.jpg"
    ["thumbnail_url"] => string(24) "content/image/thumbnail/1.jpg"
}

By default the image uploader will make optimized and thumbnail versions of your file. The original, optimized, and thumbnail versions will be placed in the directories specified in your configuration. The reason these additional files are created for images is the help optimize bandwidth usages as much as possible. For example, if a user uploads a 25MB image file, you most likely do not want to display that image every time it is requested. Rather, you can display the optimized file, which can have a significantly smaller file size. If you only need a small version of the image, request the thumbnail instead. It will most likely have an even smaller file size. The use of optimized and thumbnail images will greatly help you improve load times, and performance. If you do not wish to create these additional files, you may update your configuration to turn those off.

While the majority of the time you will only need to use your default configuration, there may be times when you wish to change a value simply for one upload. The package has setters to let you do just that. They should be called prior to uploading your file.

$this->uploader->setDirectory('base', 'newBaseDirectory');
$this->uploader->setDirectory('original', 'newOriginalDirectory');
$this->uploader->setDirectory('optimized', 'newOptimizedDirectory');
$this->uploader->setDirectory('thumbnail', 'newThumbnailDirectory');

$this->uploader->setCreateOptimized(false);
$this->uploader->setCreateThumbnails(false);

$this->uploader->setValidExtensions('image', ['jpg']);
$this->uploader->setValidMimeTypes('image', ['image/jpeg']);

$this->uploader->setMaximumUploadSize(10000000);
$this->uploader->setOptimizedImageQuality(60);
$this->uploader->setOptimizedMaximumWidth(500);
$this->uploader->setThumbnailWidth(200);

There may be times you need to 'reprocess' the images you have uploaded. You may choose to skip optimizing and creating thumbnails when an image is initially uploaded, and instead do this all at once at a specific time. You may also change your mind on configuration values. For example, you could start with an optimized image quality of 80, and decide to drop it to 60. The Uploader has a handy reprocess method available to you. Simply pass it the path to the files you would like to process, and an optional parameter to force overwriting existing files.

$this->uploader->reprocess('dogs', true);

This can be called manually in the code, but there is also a handy command available so you can schedule this to your liking. The first argument is a comma separated value of the paths you wish to process. You may also pass an optional overwrite flag.

php artisan uploader:reprocess dogs,cats --overwrite

Events

This package fires the following events:

FileOptimized
FilesReprocessed
FileThumbnailed
FileUploaded

You can use these events to hook into the operation and do things like fire off notifications.

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email browner12@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

browner12 / uploader

Maintainers

Details