Download the PHP package igaster/laravel-image-versions without Composer

How it works

Enchace your models to produce different versions of any image (eg for thumbnail/watermark etc). Produced images are saved in separate subfolders for future requests. You only have to define some operations on the Image. File management and caching are handled for you. You can use any local or remote filesystem you need!

Installation

This package depends on the Intervention package to manipulate images.

First you should install Intervention: Read the instructions. Don't forget to publish it's configuration file, we will place some options there!

Next you can install this package with:

composer require "igaster/laravel-image-versions"

How to use

This package decorates any Eloquent Model that holds a representation of an Image. To implement follow these steps:

1. Setup your model:

Your model should use the ImageVersionsTrait. For example:

The only requirement for your model is to define the relativePath() method which will return the path to the file (relative to public folder). For example if you place your images in a Photos folder and store the naked filename in the filename attribute then your implementatin could be:

PS: If you are using Amazon S3 (or any other flysystem disk) then this method should return the path to your file from your disk's root.

2. Create your Transformation classes:

You can create any number of versions of a single image. To define a version you have to create a Transformation class that extends the AbstractTransformation and implement the apply() method. You will receive an Intervention\Image\Image object, where you can perform any operations.

A short example of a trasformation class:

The Intervention package provides a rich API to edit your images. Refer to their documentation for a list of all available methods

3. Request an image version

Very simple! Call the version() method on your Eloquent model. (For the following example suppose that Photo class is an Eloquent model that stores an image's filename)

Here's what is going to happen:

• Your orinal image will be loaded from the disk
• It will be fed to the v200x200 transformation class (The apply() method will be called)
• The new image will be saved with the same name in a subfolder with the name of your transformation (v200x200 here)
• The next time you will request the same version of the same image you will receive the saved version! Build on request + cache!

On the $thumb object you received, you can retreive information about the new version of the image:

If you want to force rebuilding the new image even if it has been cached before you can call rebuildVersion() instead of version()

Passing Parameters

You may pass any number of parameters when you request a version of an Image:

You will receive these values in the apply() method of your Transformation class as additional parameters:

Please note that the the Transformation is executed only if the new image does not exist. If it has been called in the past, then the stored image will be returned instead of creating a new one. s

Using Flysystem disks (eg Amazon S3)

You can swap your local filesystem with any remote file system such as the Amazon S3.

• First define your filesystem disk in your 'filesystems.php' configuration file
• Now copy these options in the 'image.php' configuration file (it was provided by Intervention package):

Using Aliases

You can define the default namespace of your Transformation classes in image.php configuration file:

Now you have the option to use the Transformation class shortname as an alias instead of the full nampespaced classname. eg:

This is quite usefull when you are using image versions inside your Blade files.

Saving lifecycle

Two callbacks will be fired from your Transformation class before and after saving the new image. Your can implement these methods if in your classes if you need extra functionality:

Take a look at the AbstractTransformation to see how saving an image is handled by default. Note that you should not write the image to a file by yourself (writeImage('...')), since this is already handled for you.

Custom Callbacks

You can define any number of callback functions that will be executed BEFORE your Transformation is applied. To set your callbacks call beforeTransformation() from your Eloquent model, before calling the version() method:

Usefull if you want to peform some preprocessing. You can chain any number of beforeTransformation() calls.

Additionaly you can pass your own parameters to your callbacks:

Decorator Pattern: You still have your models!

Morever the return value of the version() funtion (instance of Version) is decorator that wraps your original Photo model. This means that you can perform ANY operation you could perform on your original model.

You can find more information about the decorator used at igaster/eloquent-decorator