middlewares/image-manipulation

Middleware to manipulate images on-demand

v1.3.0 2019-08-11 11:06 UTC

README

Latest Version on Packagist Software License Build Status Quality Score Total Downloads SensioLabs Insight

Middleware to transform images on demand, allowing resize, crop, rotate and transform to other formats. Uses imagecow library that can detect and use Gd and Imagick, and also has support for client hints and different automatic cropping methods.

The uri is generated encoding the image path and the manipulation options with lcobucci/jwt, to prevent alterations and image-resize attacks.

Note: To keep the SRP, this middleware does not provide the following functionalities, that should be delegated to other middleware:

  • Read the image from a directory: this library just manipulate the image response returned by inner middlewares, does NOT read in the filesystem.

  • Image caching: The library returns a response with the manipulated image but does NOT provide any caching system.

It's possible to combine this library with middlewares/filesystem that allows to read and write to the filesystem. (See example below).

Requirements

Installation

This package is installable and autoloadable via Composer as middlewares/image-manipulation.

composer require middlewares/image-manipulation

Example

The following example uses also middlewares/filesystem to read/save the manipulated images.

use Middlewares\ImageManipulation;
use Middlewares\Reader;
use Middlewares\Writer;

//You need a signature key
$key = 'sdf6&-$<@#asf';

//Manipulated images directory
$cachePath = '/path/to/cache';

//Original images directory
$imagePath = '/path/to/images';

$dispatcher = new Dispatcher([
    //read and returns the manipulated image if it's currently cached
    Reader::createFromDirectory($cachePath)->continueOnError(),

    //saves the manipulated images returned by the next middleware
    Writer::createFromDirectory($cachePath),

    //transform the image
    new Middlewares\ImageManipulation($key),

    //read and return a response with original image if exists
    Reader::createFromDirectory($imagePath)->continueOnError(),

    //In your views
    function () {
        //Create a manipulated image uri
        $uri = Middlewares\ImageManipulation::getUri('image.jpg', 'resizeCrop,500,500,CROP_ENTROPY');

        echo "<img src='{$uri}' alt='Manipulated image' width=500 height=500>";
    }
]);

$response = $dispatcher->dispatch(new ServerRequest($uri));

Options

__construct(string $signatureKey, Psr\Http\Message\StreamFactoryInterface = null)

The first argument is key used to sign the uri. This prevent attacks and alterations to the path. The second argument is the PSR-17 factory to create the response body.

clientHints(array $clientHings)

Allow to use client hints. Is disabled by default. If this method is called with the default arguments, the allowed hints are ['Dpr', 'Viewport-Width', 'Width']. Note that client hints are supported only by Chrome and Opera browsers

library(string $library)

The library to use. It can be Gd or Imagick. It's autodetected if it's not specified.

streamFactory(Psr\Http\Message\StreamFactoryInterface $streamFactory)

A PSR-17 factory to create the response body.

Helpers

ImageManipulation::getUri(string $image, string $transform, string $signatureKey = null)

To ease the uri creation this static method is provided, accepting three methods:

  • $image: The image path. This value is used to replace the uri's path of the request to the next middlewares.
  • $transform: The transformation details. You can use any method of imagecow api as a string, for example:
    • resize,200: Resize the image to 200px width (automatic height)
    • crop,200,500: Crop the image to 200x500px (centered)
    • crop,100,100,CROP_ENTROPY: Crop the image to 100x100px using the entropy method to find the most interesting point of the image
    • resize,300|rotate,90|format,jpg: Resize the image to 300px width, rotate 90º and convert to jpg
  • $signatureKey: Optional signature key to sign the uri path. If it's not provided, use the same key passed to the middleware.

Please see CHANGELOG for more information about recent changes and CONTRIBUTING for contributing details.

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