Awesome Open Source
Awesome Open Source

Laravel Guided Image

Guided Image is an image utility package for Laravel based on Intervention Image.

Built For Laravel Build Status (all) Scrutinizer Codecov License Latest Stable Version Latest Unstable Version


Guided Image for Laravel

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.

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.

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.

Installation & Usage


Install via composer; in console:

composer require reliqarts/laravel-guided-image

or require in composer.json:

    "require": {
        "reliqarts/laravel-guided-image": "^3.0"

then run composer update in your terminal to pull it in.

Finally, publish package resources and configuration:

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

You may opt to publish only configuration by using the guidedimage-config tag:

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


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

Example environment config:


These variables, and more are explained within the config file.

And... it's ready! 👌


To use Guided Image you must do just that from your Image model. 😏

Implement the ReliqArts\GuidedImage\Contract\GuidedImage contract and use the ReliqArts\GuidedImage\Concern\Guided trait, e.g:

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.

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

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

class ImageController extends Controller implements ImageGuide
    use Guide;

See example here.


Safely Remove Image (dissociate & conditionally delete the image)

An guided image instance is removed by calling the remove method. e.g:


$force is optional and is false by default.

Link Generation

You may retrieve guided links to resized or cropped images like so:

// 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.

Have a look at the GuidedImage contract for more info on model functions.

For more info on controller functions see the ImageGuide contract.


Your actually routes will depend heavily on your custom configuration. Here is an example of what the routes may look like:

|| GET|HEAD | image/.dum//{width}-{height}/{color?}/{fill?}           | image.dummy           | App\Http\Controllers\[email protected]       | web |
|| GET|HEAD | image/.res/{image}//{width}-{height}/{aspect?}/{upSize?}| image.resize          | App\Http\Controllers\[email protected]     | web |
|| GET|HEAD | image/.tmb/{image}//m.{method}/{width}-{height}         | image.thumb           | App\Http\Controllers\[email protected]       | web |
|| GET|HEAD | image/empty-cache                                       | image.empty-cache     | App\Http\Controllers\[email protected]  | web |

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
php (16,624
hacktoberfest (4,263
laravel (1,673
view (209
routing (148
upload (117
trait (27