reliqarts/guided-image

Simplified and ready image manipulation for Laravel 5 via intervention image.

Laravel Guided Image

Guided Image is an image utility package for Laravel based on Intervention Image., _(*1)

, _(*2)

 , _(*3)

, _(*4)

Key Features

• On-the-fly image resizing
• On-the-fly thumbnail generation
• Image uploading
• Smart image reuse; mitigating against double uploads and space resource waste.

Guided Image can be integrated seamlessly with your existing image model., _(*5)

Guided Routes

The package provides routes for generating resized/cropped/dummy images. - Routes are configurable you you may set any middleware and prefix you want. - Generated images are cached to disk to avoid regenerating frequently accessed images and reduce overhead., _(*6)

Image file reuse

For situations where different instances of models use the same image. - The package provides a safe removal feature which allows images to be detached and only deleted from disk if not being used elsewhere. - An overridable method is used to determine when an image should be considered safe to delete., _(*7)

Installation & Usage

Installation

Install via composer; in console:, _(*8)

composer require reliqarts/laravel-guided-image

or require in composer.json:, _(*9)

{
    "require": {
        "reliqarts/laravel-guided-image": "^5.0"
    }
}

then run composer update in your terminal to pull it in., _(*10)

Finally, publish package resources and configuration:, _(*11)

php artisan vendor:publish --provider="ReliqArts\GuidedImage\ServiceProvider"

You may opt to publish only configuration by using the guidedimage-config tag:, _(*12)

php artisan vendor:publish --provider="ReliqArts\GuidedImage\ServiceProvider" --tag="guidedimage-config"

Setup

Set the desired environment variables so the package knows your image model, controller(s), etc., _(*13)

Example environment config:, _(*14)

GUIDED_IMAGE_MODEL=Image
GUIDED_IMAGE_CONTROLLER=ImageController
GUIDED_IMAGE_ROUTE_PREFIX=image
GUIDED_IMAGE_SKIM_DIR=images

These variables, and more are explained within the config file., _(*15)

And... it's ready! :ok_hand:, _(*16)

Usage

To use Guided Image you must do just that from your Image model. :smirk:, _(*17)

Implement the ReliqArts\GuidedImage\Contract\GuidedImage contract and use the ReliqArts\GuidedImage\Concern\Guided trait, e.g:, _(*18)

use Illuminate\Database\Eloquent\Model;
use ReliqArts\GuidedImage\Concern\Guided;
use ReliqArts\GuidedImage\Contract\GuidedImage;

class Image extends Model implements GuidedImage
{
    use Guided;

    // ... properties and methods
}

See example here., _(*19)

Implement the ReliqArts\GuidedImage\Contract\ImageGuide contract and use the ReliqArts\GuidedImage\Concern\Guide trait from your ImageController, e.g:, _(*20)

use ReliqArts\GuidedImage\Contract\ImageGuide;
use ReliqArts\GuidedImage\Concern\Guide;

class ImageController extends Controller implements ImageGuide
{
    use Guide;
}

See example here., _(*21)

Features

Safely Remove Image (dissociate & conditionally delete the image)

An guided image instance is removed by calling the remove method. e.g:, _(*22)

$oldImage->remove($force);

$force is optional and is false by default., _(*23)

Link Generation

You may retrieve guided links to resized or cropped images like so:, _(*24)

// resized image:
$linkToImage = $image->routeResized([
    '550',      // width
    '_',        // height, 'null' is OK 
    '_',        // keep aspect ratio? true by default, 'null' is OK
    '_',        // allow upsize? false by default, 'null' is OK
]);

// thumbnail:
$linkToImage = $image->routeThumbnail([
    'crop',     // method: crop|fit
    '550',      // width
    '_',        // height
]);

NB: In the above example _ resolves to null., _(*25)

Have a look at the GuidedImage contract for more info on model functions., _(*26)

For more info on controller functions see the ImageGuide contract., _(*27)

Routes

Your actually routes will depend heavily on your custom configuration. Here is an example of what the routes may look like:, _(*28)

|| GET|HEAD | image/.dum//{width}-{height}/{color?}/{fill?}           | image.dummy           | App\Http\Controllers\ImageController@dummy       | web |
|| GET|HEAD | image/.res/{image}//{width}-{height}/{aspect?}/{upSize?}| image.resize          | App\Http\Controllers\ImageController@resized     | web |
|| GET|HEAD | image/.tmb/{image}//m.{method}/{width}-{height}         | image.thumb           | App\Http\Controllers\ImageController@thumb       | web |
|| GET|HEAD | image/empty-cache                                       | image.empty-cache     | App\Http\Controllers\ImageController@emptyCache  | web |