PHPackages                             middlewares/image-manipulation - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. middlewares/image-manipulation

ActiveLibrary[HTTP & Networking](/categories/http)

middlewares/image-manipulation
==============================

Middleware to manipulate images on-demand

v3.0.0(1y ago)104.1k2[1 issues](https://github.com/middlewares/image-manipulation/issues)1MITPHPPHP ^7.4 || ^8.0CI passing

Since Oct 7Pushed 1y ago3 watchersCompare

[ Source](https://github.com/middlewares/image-manipulation)[ Packagist](https://packagist.org/packages/middlewares/image-manipulation)[ Docs](https://github.com/middlewares/image-manipulation)[ RSS](/packages/middlewares-image-manipulation/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (10)Versions (18)Used By (1)

middlewares/image-manipulation
==============================

[](#middlewaresimage-manipulation)

[![Latest Version on Packagist](https://camo.githubusercontent.com/a7fd36dca16de5eb4beab09b35726ced49df3949a125149f8fdffae0c1e61a4f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6964646c6577617265732f696d6167652d6d616e6970756c6174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/middlewares/image-manipulation)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Testing](https://github.com/middlewares/image-manipulation/workflows/testing/badge.svg)](https://github.com/middlewares/image-manipulation/workflows/testing/badge.svg)[![Total Downloads](https://camo.githubusercontent.com/443d83d14bc6b46173bc8e7fe7bbf3d34fb042a1b58728e8396e771c45fa5173/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6964646c6577617265732f696d6167652d6d616e6970756c6174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/middlewares/image-manipulation)

Middleware to transform images on demand, allowing resize, crop, rotate and transform to other formats. Uses [imagecow](https://github.com/oscarotero/imagecow) library that can detect and use `Gd` and `Imagick`, and also has support for [client hints](https://www.smashingmagazine.com/2016/01/leaner-responsive-images-client-hints/) and different [automatic cropping methods](https://github.com/oscarotero/imagecow#automatic-cropping).

The uri is generated encoding the image path and the manipulation options with [lcobucci/jwt](https://github.com/lcobucci/jwt/), to prevent alterations and image-resize attacks.

**Note:** To keep the [SRP](https://en.wikipedia.org/wiki/Single_responsibility_principle), 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](https://github.com/middlewares/filesystem) that allows to read and write to the filesystem. (See [example](#example) below).

Requirements
------------

[](#requirements)

- PHP >= 7.2
- A [PSR-7 http library](https://github.com/middlewares/awesome-psr15-middlewares#psr-7-implementations)
- A [PSR-15 middleware dispatcher](https://github.com/middlewares/awesome-psr15-middlewares#dispatcher)

Installation
------------

[](#installation)

This package is installable and autoloadable via Composer as [middlewares/image-manipulation](https://packagist.org/packages/middlewares/image-manipulation).

```
composer require middlewares/image-manipulation
```

Example
-------

[](#example)

The following example uses also [middlewares/filesystem](https://github.com/middlewares/filesystem) to read/save the manipulated images.

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

//You need a signature key
$key = 'sdf6&-$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 "";
    }
]);

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

Usage
-----

[](#usage)

You need a key to sign the uri. This prevent attacks and alterations to the path.

```
$key = 'super-secret-key';

$imageManipulation = new Middlewares\ImageManipulation($key);
```

Optionally, you can provide a `Psr\Http\Message\StreamFactoryInterface` as the second argument to create the new response stream with the image. If it's not defined, [Middleware\\Utils\\Factory](https://github.com/middlewares/utils#factory) will be used to detect it automatically.

```
$key = 'super-secret-key';
$streamFactory = new MyOwnStreamFactory();

$imageManipulation = new Middlewares\ImageManipulation($key, $streamFactory);
```

### clientHints

[](#clienthints)

This option allows to use client hints, that 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](http://caniuse.com/#feat=client-hints-dpr-width-viewport)

### library

[](#library)

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

Helpers
-------

[](#helpers)

### getUri

[](#geturi)

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

- `$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](https://github.com/oscarotero/imagecow#execute-multiple-functions) 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.

```
use Middlewares\ImageManipulation;

$image = '/img/avatar.jpg';
$transform = 'resizeCrop,200,200';

$uri = ImageManipulation::getUri($image, $transform);

echo '';
```

---

Please see [CHANGELOG](CHANGELOG.md) for more information about recent changes and [CONTRIBUTING](CONTRIBUTING.md) for contributing details.

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

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance44

Moderate activity, may be stable

Popularity26

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 93.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~193 days

Recently: every ~528 days

Total

17

Last Release

420d ago

Major Versions

v0.5.0 → v1.0.02018-01-26

v1.3.0 → v2.0.02019-11-30

v2.0.1 → v3.0.02025-03-22

PHP version history (5 changes)v0.1.0PHP ^5.6 || ^7.0

v0.5.0PHP ^7.0

v2.0.0PHP ^7.2

v2.0.1PHP ^7.2 || ^8.0

v3.0.0PHP ^7.4 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/e99df56b617f4af8cf0556a51a0ca20c7420104920c57d7e9eab093f92bb744f?d=identicon)[oscarotero](/maintainers/oscarotero)

![](https://www.gravatar.com/avatar/42e0d72f42eb7d84f67e20d28606da42e5a3248ca908b1eadb4366aafeae2561?d=identicon)[filisko](/maintainers/filisko)

---

Top Contributors

[![oscarotero](https://avatars.githubusercontent.com/u/377873?v=4)](https://github.com/oscarotero "oscarotero (74 commits)")[![filisko](https://avatars.githubusercontent.com/u/8798694?v=4)](https://github.com/filisko "filisko (5 commits)")

---

Tags

httpimage-manipulationmiddlewarepsr-15httppsr-7middlewareimagepsr-15client-hints

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/middlewares-image-manipulation/health.svg)

```
[![Health](https://phpackages.com/badges/middlewares-image-manipulation/health.svg)](https://phpackages.com/packages/middlewares-image-manipulation)
```

###  Alternatives

[middlewares/request-handler

Middleware to execute request handlers

451.6M26](/packages/middlewares-request-handler)[middlewares/fast-route

Middleware to use FastRoute

96191.1k15](/packages/middlewares-fast-route)[middlewares/negotiation

Middleware to implement content negotiation

47442.1k11](/packages/middlewares-negotiation)[middlewares/trailing-slash

Middleware to normalize the trailing slash of the uri path

32506.3k11](/packages/middlewares-trailing-slash)[middlewares/payload

Middleware to parse the body of the request with support for json, csv and url-encode

32466.8k17](/packages/middlewares-payload)[middlewares/http-authentication

Middleware to implement Basic and Digest Http authentication

35302.0k2](/packages/middlewares-http-authentication)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)