PHPackages                             storyblok/php-image-service - 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. [Image & Media](/categories/media)
4. /
5. storyblok/php-image-service

ActiveLibrary[Image & Media](/categories/media)

storyblok/php-image-service
===========================

PHP Client for Storyblok Image Service

0.5.0(3mo ago)519.2k↓19.9%1[3 PRs](https://github.com/storyblok/php-image-service/pulls)1MITPHPPHP >=8.3CI passing

Since Jan 19Pushed 1mo ago8 watchersCompare

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

READMEChangelog (6)Dependencies (13)Versions (12)Used By (1)

 [![Storyblok PHP Image Service](assets/php-image-service-github-repository.png)](assets/php-image-service-github-repository.png)Storyblok PHP Image Service
===========================

[](#storyblok-php-image-service)

Co-created with [SensioLabs](https://sensiolabs.com/), the creators of Symfony.

BranchPHPCode Coverage`master`[![PHP](https://github.com/storyblok/php-image-service/actions/workflows/ci.yaml/badge.svg)](https://github.com/storyblok/php-image-service/actions/workflows/ci.yaml)[![codecov](https://camo.githubusercontent.com/28c9045d14fd03b4ed130ac886cb09bff2396a802c40e6eea518ab51ebf83884/68747470733a2f2f636f6465636f762e696f2f67682f73746f7279626c6f6b2f7068702d696d6167652d736572766963652f67726170682f62616467652e737667)](https://codecov.io/gh/storyblok/php-image-service)Warning

This package is currently **experimental**. Breaking changes may be introduced with any release until a stable version is reached. Use with caution in production environments.

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

[](#installation)

```
composer require storyblok/php-image-service
```

Usage
-----

[](#usage)

```
use Storyblok\ImageService\Image;

$image = new Image('https://a.storyblok.com/f/287488/1400x900/2fc896c892/image.jpg');

// Chain multiple operations
$url = $image
    ->resize(800, 600)
    ->format('webp')
    ->quality(80)
    ->toString();
```

Fluent Interface
----------------

[](#fluent-interface)

The `Image` class supports a fluent interface, allowing you to chain multiple operations together. Each method returns a new `Image` instance, making the original instance immutable.

```
use Storyblok\ImageService\Image;

$image = new Image('https://a.storyblok.com/f/287488/1400x900/2fc896c892/image.jpg');

// Chain as many operations as needed
$url = $image
    ->crop(100, 50, 800, 600)
    ->resize(400, 300)
    ->flipX()
    ->rotate(90)
    ->brightness(10)
    ->quality(80)
    ->format('webp')
    ->grayscale()
    ->toString();

// The original image remains unchanged (immutability)
$original = new Image('https://a.storyblok.com/f/287488/1400x900/2fc896c892/image.jpg');
$resized = $original->resize(800, 600);
$withQuality = $resized->quality(80);

// Each variable holds a different state:
// $original    -> original URL
// $resized     -> resized URL
// $withQuality -> resized + quality URL
```

Available Operations
--------------------

[](#available-operations)

### Resize

[](#resize)

Resize an image to specific dimensions. If only width or height is provided, the other dimension will be calculated to maintain the aspect ratio.

```
use Storyblok\ImageService\Image;

$image = new Image('https://a.storyblok.com/f/287488/1400x900/2fc896c892/image.jpg');

// Resize to specific dimensions
$image->resize(800, 600);

// Resize by width only (height auto-calculated)
$image->resize(800, 0);

// Resize by height only (width auto-calculated)
$image->resize(0, 600);
```

### Fit-In

[](#fit-in)

Fit the image within a given width and height while maintaining aspect ratio.

```
$image->fitIn(800, 600);
```

### Crop

[](#crop)

Crop the image by specifying the top-left and bottom-right coordinates.

```
// Crop from position (100, 100) to (500, 400)
$image->crop(100, 100, 500, 400);

// Crop from top-left (0, 0) to specific point
$image->crop(0, 0, 500, 400);
```

### Format

[](#format)

Convert the image to a different format. Supported formats: `webp`, `jpeg`, `png`, `avif`.

```
$image->format('webp');
$image->format('jpeg');
$image->format('png');
$image->format('avif');
```

### Quality

[](#quality)

Set the image quality (0-100).

```
$image->quality(80);
```

### Blur

[](#blur)

Apply a blur effect with radius (0-150) and optional sigma (0-150).

```
// Apply blur with radius only
$image->blur(10);

// Apply blur with radius and sigma
$image->blur(10, 5);
```

### Brightness

[](#brightness)

Adjust image brightness (-100 to 100).

```
// Increase brightness
$image->brightness(50);

// Decrease brightness
$image->brightness(-30);
```

### Rotate

[](#rotate)

Rotate the image by a specific angle. Only 0, 90, 180, and 270 degrees are supported.

```
$image->rotate(90);
$image->rotate(180);
$image->rotate(270);
```

### Flip

[](#flip)

Flip the image horizontally or vertically.

```
// Flip horizontally
$image->flipX();

// Flip vertically
$image->flipY();

// Flip both
$image->flipX()->flipY();
```

### Grayscale

[](#grayscale)

Convert the image to grayscale.

```
$image->grayscale();
```

### Focal Point

[](#focal-point)

Set a focal point for smart cropping using a string in format `x1xy1:x2xy2`.

```
// Set focal point coordinates
$image->focalPoint('100x100:300x300');

// Use value from Storyblok asset focus field
$image->focalPoint('719x153:720x154');
```

### Rounded Corners

[](#rounded-corners)

Apply rounded corners to the image.

```
// Simple rounded corners with radius
$image->roundedCorners(20);

// With ellipsis for elliptical corners
$image->roundedCorners(20, 10);

// With custom background color (RGB)
$image->roundedCorners(20, null, 255, 0, 0);

// With transparent background
$image->roundedCorners(20, null, 255, 255, 255, true);
```

### Fill

[](#fill)

Set a fill color for fit-in operations. Accepts `transparent` or a hex color code.

```
// Fill with hex color
$image->fitIn(800, 600)->fill('#FF0000');
$image->fitIn(800, 600)->fill('FF0000');
$image->fitIn(800, 600)->fill('#F00');

// Fill with transparent
$image->fitIn(800, 600)->fill('transparent');
```

### No Upscale

[](#no-upscale)

Prevent the image from being upscaled beyond its original dimensions.

```
$image->resize(2000, 2000)->noUpscale();
```

### Get Image Metadata

[](#get-image-metadata)

Retrieve information about the image.

```
$image = new Image('https://a.storyblok.com/f/287488/1400x900/2fc896c892/my-image.jpg');

// Get dimensions
$image->getWidth();     // 1400
$image->getHeight();    // 900

// Get file info
$image->getName();      // "my-image"
$image->getExtension(); // "jpg"

// Extension updates when format changes
$formatted = $image->format('webp');
$formatted->getExtension(); // "webp"
```

Limitations
-----------

[](#limitations)

The following limitations apply:

- **URL Format**: The image URL must contain dimensions in the format `/{width}x{height}/` (e.g., `/1400x900/`). URLs without this pattern will throw an `InvalidArgumentException`.
- **Rotation Angles**: Only 0, 90, 180, and 270 degree rotations are supported. Arbitrary angles are not available.
- **Blur Constraints**: The blur sigma cannot be set to a value greater than 0 when the radius is 0.
- **Quality Range**: Quality must be between 0 and 100.
- **Brightness Range**: Brightness must be between -100 and 100.
- **Blur Range**: Both radius and sigma must be between 0 and 150.
- **RGB Values**: For rounded corners, RGB values must be between 0 and 255.
- **Format Values**: Format must be one of `webp`, `jpeg`, `png`, or `avif`.

License
-------

[](#license)

This project is licensed under the MIT License. Please see [License File](LICENSE) for more information.

###  Health Score

48

—

FairBetter than 95% of packages

Maintenance85

Actively maintained with recent releases

Popularity34

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 81.3% 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 ~0 days

Total

6

Last Release

115d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5502146a107d9e193823fac44e6fb4ef7a8f89d1e36726e8d42211e27833887f?d=identicon)[delooks](/maintainers/delooks)

---

Top Contributors

[![silasjoisten](https://avatars.githubusercontent.com/u/10114981?v=4)](https://github.com/silasjoisten "silasjoisten (13 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![edodusi](https://avatars.githubusercontent.com/u/2177962?v=4)](https://github.com/edodusi "edodusi (1 commits)")[![OskarStark](https://avatars.githubusercontent.com/u/995707?v=4)](https://github.com/OskarStark "OskarStark (1 commits)")

---

Tags

phpstoryblok

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/storyblok-php-image-service/health.svg)

```
[![Health](https://phpackages.com/badges/storyblok-php-image-service/health.svg)](https://phpackages.com/packages/storyblok-php-image-service)
```

###  Alternatives

[infection/infection

Infection is a Mutation Testing framework for PHP. The mutation adequacy score can be used to measure the effectiveness of a test set in terms of its ability to detect faults.

2.2k26.2M1.8k](/packages/infection-infection)[danog/madelineproto

Async PHP client API for the telegram MTProto protocol.

3.4k855.0k18](/packages/danog-madelineproto)[humbug/box

Fast, zero config application bundler with PHARs.

1.3k801.5k69](/packages/humbug-box)[storyblok/php-content-api-client

PHP Client for Storyblok Content API

11136.8k4](/packages/storyblok-php-content-api-client)[veewee/xml

XML without worries

1835.9M29](/packages/veewee-xml)[php-soap/wsdl-reader

A WSDL reader in PHP

212.3M9](/packages/php-soap-wsdl-reader)

PHPackages © 2026

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