PHPackages                             backstage/php-uploadcare-transformations - 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. backstage/php-uploadcare-transformations

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

backstage/php-uploadcare-transformations
========================================

Composer package for generating URLs using Uploadcare for image transformations and processing.

v1.2.0(9mo ago)14313↓100%[3 PRs](https://github.com/backstagephp/php-uploadcare-transformations/pulls)MITPHPPHP ^8.1|^8.2|^8.3CI passing

Since Aug 17Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/backstagephp/php-uploadcare-transformations)[ Packagist](https://packagist.org/packages/backstage/php-uploadcare-transformations)[ Docs](https://github.com/backstagephp/php-uploadcare-transformations)[ GitHub Sponsors](https://github.com/backstagephp)[ RSS](/packages/backstage-php-uploadcare-transformations/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (32)Used By (0)

Easy [Uploadcare](https://uploadcare.com/?via=vk10) Image Transformation URLs generation
========================================================================================

[](#easy-uploadcare-image-transformation-urls-generation)

[![Total Downloads](https://camo.githubusercontent.com/d648b4525fe22812d150dfac352c18b25ff89bdad7e79b7a022a503fe656b7ae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6261636b73746167652f7068702d75706c6f6164636172652d7472616e73666f726d6174696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/backstage/php-uploadcare-transformations)[![Tests](https://github.com/backstagephp/php-uploadcare-transformations/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/backstage/php-uploadcare-transformations/actions/workflows/run-tests.yml)[![PHPStan](https://github.com/backstagephp/php-uploadcare-transformations/actions/workflows/phpstan.yml/badge.svg?branch=main)](https://github.com/backstage/php-uploadcare-transformations/actions/workflows/phpstan.yml)[![GitHub release (latest by date)](https://camo.githubusercontent.com/1a8737dac66dfe29f278e0b2f3f2a891662ad73651fa50f2b8b11c0dd0dc269b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6261636b73746167652f7068702d75706c6f6164636172652d7472616e73666f726d6174696f6e73)](https://camo.githubusercontent.com/1a8737dac66dfe29f278e0b2f3f2a891662ad73651fa50f2b8b11c0dd0dc269b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6261636b73746167652f7068702d75706c6f6164636172652d7472616e73666f726d6174696f6e73)[![Packagist PHP Version Support](https://camo.githubusercontent.com/d6ecf987663b27972fe8df7da40c8a911123d6ae93c9e21728f7dd22f940f248/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6261636b73746167652f7068702d75706c6f6164636172652d7472616e73666f726d6174696f6e73)](https://camo.githubusercontent.com/d6ecf987663b27972fe8df7da40c8a911123d6ae93c9e21728f7dd22f940f248/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6261636b73746167652f7068702d75706c6f6164636172652d7472616e73666f726d6174696f6e73)[![Latest Version on Packagist](https://camo.githubusercontent.com/97bd83d941f799cdbdc7e55dcdc4bc2f028cb85b0cae22ff89597f4cb57e2ab6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6261636b73746167652f7068702d75706c6f6164636172652d7472616e73666f726d6174696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/backstage/php-uploadcare-transformations)

Generate [Uploadcare](https://uploadcare.com/?via=vk10) image processing URLs to transform and process your images. No need to write or generate the URL yourself. Just pass the UUID of the file, optionally pass the custom CDN and chain the methods you want to apply and the package generates the URL for you.

- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Documentation](#documentation)
    - [Using percentages or pixels as parameter](#using-percentages-or-pixels-as-parameter)
    - [List of possible transformations](#list-of-possible-transformations)
- [Usage](#usage-1)
    - [Auto rotate](#auto-rotate)
    - [Basic color adjustments](#basic-color-adjustments)
    - [Blur](#blur)
    - [Blur faces](#blur-faces)
    - [Blur region](#blur-region)
    - [Convert to sRGB](#convert-to-srgb)
    - [Crop](#crop)
    - [Crop by objects](#crop-by-objects)
    - [Crop by ratio](#crop-by-ratio)
    - [Enhance](#enhance)
    - [Filter](#filter)
    - [Flip](#flip)
    - [Format](#format)
    - [Grayscale](#grayscale)
    - [ICC profile size threshold](#icc-profile-size-threshold)
    - [Invert](#invert)
    - [Miror](#miror)
    - [Overlay](#overlay)
    - [Preview](#preview)
    - [Progressive](#progressive)
    - [Quality](#quality)
    - [Rasterize](#rasterize)
    - [Resize](#resize)
    - [Rotate](#rotate)
    - [Scale crop](#scale-crop)
    - [Set fill](#set-fill)
    - [Sharpen](#sharpen)
    - [Smart crop](#smart-crop)
    - [Smart resize](#smart-resize)
    - [Zoom objects](#zoom-objects)
- [Testing](#testing)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Security Vulnerabilities](#security-vulnerabilities)
- [Credits](#credits)
- [License](#license)

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

[](#requirements)

- PHP 8.1+

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

[](#installation)

You can install the package via composer:

```
composer require backstage/php-uploadcare-transformations
```

Usage
-----

[](#usage)

1. Import UploadcareTransformation.
2. Get the UUID of the file you want to show.
3. Set your CDN url (optional).
4. Create the transformation URL by chaining one or multiple methods to the UploadcareTransformation class. You can chain as much methods as you want.
5. Use the output of the transformation as image source.

```
use Backstage\UploadcareTransformations\UploadcareTransformation;

$uuid = '12a3456b-c789-1234-1de2-3cfa83096e25';
$cdnUrl = 'https://example.com/cdn/';

$transformation = (new UploadcareTransformation($uuid, $cdnUrl));

$url = $transformation->crop(width: 320, height: '50p', offsetX: 'center')->setFill(color: 'ffffff');

echo $url;
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/-/crop/320x50p/center/-/set_fill/ffffff
```

If you prefer to use a shorter version you can also use the helper method:

```
$uuid = '12a3456b-c789-1234-1de2-3cfa83096e25';
$cdnUrl = 'https://example.com/cdn/';

$url = uc($uuid, $cdnUrl)
        ->crop(width: 320, height: '50p', offsetX: 'center')
        ->setFill(color: 'ffffff')
        ->getUrl();

echo $url;
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/-/crop/320x50p/center/-/set_fill/ffffff
```

### Reusing Objects for Multiple Transformations

[](#reusing-objects-for-multiple-transformations)

When you want to reuse an object for multiple transformations (like creating different formats for a picture element), you can use the `clone()` method. This is especially useful when you want to create multiple versions of the same image with different formats or transformations.

```
$image = uc('your-uuid-here')->resize(width: 1024);

// Create different versions of the same image
$webp = $image->clone()->format('webp');
$jpeg = $image->clone()->format('jpeg');
$png = $image->clone()->format('png')->quality('best');
```

You can also use the `uc_clone()` helper function:

```
$image = uc('your-uuid-here')->resize(width: 1024);
$webp = uc_clone($image)->format('webp');
$jpeg = uc_clone($image)->format('jpeg');
```

This is particularly useful in Blade components for creating responsive images:

```

```

### Using the Laravel framework

[](#using-the-laravel-framework)

When you are using the Laravel framework it might be better to define the CDN in your `.env` file and get the value from the `.env` file in a config file. You can create a `config/uploadcare` config or add it to the `config/services` file.

Your `.env` file:

```
UPLOADCARE_CDN_URL=https://ucarecdn.com
UPLOADCARE_PROXY_URL=https://endpoint.ucr.io
```

Add to `config/services.php` file:

```
'uploadcare' => [
    'cdn_url' => env('UPLOADCARE_CDN_URL', 'https://ucarecdn.com'),
    'proxy_url' => env('UPLOADCARE_PROXY_URL', 'https://endpoint.ucr.io'),
],
```

In your code:

```
$url = uc($uuid, config('services.uploadcare.cdn_url'))->crop(width: 320, height: '50p', offsetX: 'center')->setFill(color: 'ffffff');
```

Documentation
-------------

[](#documentation)

### Using percentages or pixels as parameter

[](#using-percentages-or-pixels-as-parameter)

In some of the methods you can pass parameters in various ways. For example in the [scaleCrop()](/src/Transformations/ScaleCrop.php) method you can pass the offset in the form of a percentage or pixels. To make it easier to recognize when a pixel or percentage is used you can pass the parameters as following.

```
// Using percentages
$url = $transformation->scaleCrop(width: 320, height: 320, offsetX: '50p', offsetY: '60p');
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/scale_crop/320x320/50px60p/

// Using pixels
$url = $transformation->scaleCrop(width: 320, height: 320, offsetX: 50, offsetY: 60);
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/scale_crop/320x320/50x60/
```

> As stated in the Uploadcare Documentation, in URLs, % is an escape character and should be encoded with %25 escape sequence, e.g. /scale\_crop/440x440/80%25,80%25/. For convenience, we can use the p shortcut for percent which doesn't require encoding.

### List of possible transformations

[](#list-of-possible-transformations)

Each transformation follows the documentation on Uploadcare which you may find [here](https://uploadcare.com/docs/). The current list of possible transformations and where to find the documentation:

TransformationUploadcare Documentation link[Auto rotate](#auto-rotate)[Link](https://uploadcare.com/docs/transformations/image/rotate-flip/#operation-autorotate)[Basic color adjustments](#basic-color-adjustments)[Link](https://uploadcare.com/docs/transformations/image/colors/#image-colors-operations)[Blur](#blur)[Link](https://uploadcare.com/docs/transformations/image/blur-sharpen/#operation-blur)[Blur faces](#blur-faces)[Link](https://uploadcare.com/docs/transformations/image/blur-sharpen/#operation-blur-region-faces)[Blur region](#blur-region)[Link](https://uploadcare.com/docs/transformations/image/blur-sharpen/#operation-blur-region)[Convert to sRGB](#convert-to-srgb)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-srgb)[Crop](#crop)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-crop)[Crop by objects](#crop-by-objects)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-crop-tags)[Crop by ratio](#crop-by-ratio)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-crop-aspect-ratio)[Enhance](#enhance)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-enhance)[Filter](#filter)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-filter)[Flip](#flip)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-flip)[Format](#format)[Link](https://uploadcare.com/docs/transformations/image/compression/#operation-format)[Grayscale](#grayscale)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-grayscale)[ICC profile size threshold](#icc-profile-size-threshold)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-max-icc-size)[Invert](#invert)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-inverting)[Miror](#miror)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-mirror)[Overlay](#overlay)[Link](https://uploadcare.com/docs/transformations/image/overlay/#overlay-image)[Preview](#preview)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-preview)[Progressive](#progressive)[Link](https://uploadcare.com/docs/transformations/image/compression/#operation-progressive)[Quality](#quality)[Link](https://uploadcare.com/docs/transformations/image/compression/#operation-quality)[Rasterize](#rasterize)[Link](https://uploadcare.com/docs/transformations/image/#svg)[Resize](#resize)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-resize)[Rotate](#rotate)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-rotate)[Scale crop](#scale-crop)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-scale-crop)[Set fill](#set-fill)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-setfill)[Sharpen](#sharpen)[Link](https://uploadcare.com/docs/transformations/image/colors/#operation-sharpen)[Smart crop](#smart-crop)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-smart-crop)[Smart resize](#smart-resize)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-smart-resize)[Zoom objects](#zoom-objects)[Link](https://uploadcare.com/docs/transformations/image/resize-crop/#operation-zoom-objects)Usage
-----

[](#usage-1)

### Adding filename

[](#adding-filename)

Original filenames can be accessed via Uploadcare's REST API. This can be done by making a request to receive a JSON response with file parameters including `original_filename`.

You can set an optional filename that users will see instead of the original name:

```
$url = $transformation->autoRotate(false)->filename('my-filename.jpg');
// https://example.com/cdn/.../-/autorotate/no/my-filename.jpg
```

> Please note that the filename should comply with [file name conventions](https://tools.ietf.org/html/rfc3986#section-3.3). For more more information about how to use filenames please check the [Uploadcare API documentation](https://uploadcare.com/docs/delivery/cdn/#cdn-filename).

### Auto rotate

[](#auto-rotate)

The default behavior goes with parsing EXIF tags of original images and rotating them according to the “Orientation” tag. Using `false` as parameter allows turning off the default behavior.

```
$url = $transformation->autoRotate(false);
// https://example.com/cdn/.../-/autorotate/no/

$url = $transformation->autoRotate(true);
// https://example.com/cdn/.../-/autorotate/yes/
```

### Basic color adjustments

[](#basic-color-adjustments)

The value parameter controls the strength of any applied adjustment. Ranges of the value parameter differ between operations. There also is a zero point for each operation — the value producing outputs equal to original images.

Adjustment (color) must be one of the following values: `brightness`, `exposure`, `contrast`, `saturation`, `gamma`, `vibrance`, `warmth`.

For a complete overview of allowed values based upon the chosen adjustment, take a look at the [Uploadcare Documentation](https://uploadcare.com/docs/transformations/image/colors/#image-colors-operations).

```
$url = $transformation->basicColorAdjustments(color: 'brightness', value: 50);
// https://example.com/cdn/.../-/adjust/brightness/50/
```

### Blur

[](#blur)

Blurs images by the strength factor. The filtering mode is Gaussian Blur, where strength parameter sets the blur radius — effect intensity.

```
$url = $transformation->blur(strength: 50, amount: null);
// https://example.com/cdn/.../-/blur/50/
```

### Blur faces

[](#blur-faces)

When faces is specified the regions are selected automatically by utilizing face detection.

```
$url = $transformation->blurFaces(strength: 50);
// https://example.com/cdn/.../-/blur_faces/50/
```

### Blur region

[](#blur-region)

Blurs the specified region of the image by the strength factor. The filtering mode is Gaussian Blur, where strength parameter sets the blur radius — effect intensity.

Dimensions and coordinates must be pixels or percentages.

```
// Using pixels.
$url = $transformation->blurRegion(dimensionX: 250, dimensionY: 250, coordinateX: 50, coordinateY: 50, strength: 200);
// https://example.com/cdn/.../-/blur_region/250/250/50/50/200/

// Using percentages.
$url = $transformation->blurRegion(dimensionX: '50p', dimensionY: '50p', coordinateX: '80p', coordinateY: '20p', strength: 200);
// https://example.com/cdn/.../-/blur_region/50p/50p/80p,20p/200/
```

### Convert to sRGB

[](#convert-to-srgb)

The operation sets how Uploadcare behaves depending on different color profiles of uploaded images. See the [Uploadcare Documentation](https://uploadcare.com/docs/transformations/image/colors/#operation-srgb) to learn more about the possible outcomes.

The profile parameter must be one of the following values: `fast`, `icc`, `keep_profile`.

```
$url = $transformation->convertToSRGB(profile: 'icc');
// https://example.com/cdn/.../-/srgb/icc/
```

### Crop

[](#crop)

Crops an image by using specified dimensions and alignment.

Dimensions parameters can be in pixels or percentages. To see how pixels or percentages can be used, see the [Using percentages or pixels as parameter](#using-percentages-or-pixels-as-parameter) paragraph.

Alignment can also be in pixels and percentages but also a shortcut can be used. The possible values are: `top`, `center`, `bottom`, `left`, `right`.

```
// Using percentages and a shortcut.
$url = $transformation->crop(width: 100, height: '50p', offsetX: 'center');
// https://example.com/cdn/.../-/crop/100x50p/center/

// Using pixels only.
$url = $transformation->crop(width: 100, height: 100, offsetX: 50, offsetY: 50);
// https://example.com/cdn/.../-/crop/100x100/50,50/

// Using both pixels and percentages.
$url = $transformation->crop(width: 100, height: '50p', offsetX: '25p', offsetY: '25p');
// https://example.com/cdn/.../-/crop/100x50p/25p,25p/
```

### Crop by objects

[](#crop-by-objects)

Crops the image to the object specified by the tag parameter.

Tag can be one of `face` or `image`.

Ratio are two numbers greater than zero separated by :. Ratio is the quotient from the division of these numbers.

Dimensions and alignment must be set in percentages. In case of the alignment you can also use the shortcut. The possible values are: `top`, `center`, `bottom`, `left`, `right`. If alignment is not specified, `center` value is used.

> Dimensions should be relative when used with a tag. So you are required to set both width and height with pixels.

```
// Using no ratio, percentages and pixels combined.
$url = $transformation->cropByObjects(tag: 'face', ratio: null, width: '50p', height: '50p');
// https://example.com/cdn/../-/crop/face/50px50p/

// Using ratio, percentages and a shortcut.
$url = $transformation->cropByObjects(tag: 'face', ratio: '4:3', width: '50p', height: '50p', offsetX: 'bottom');
// https://example.com/cdn/../-/crop/face/4:3/50px50p/bottom/
```

### Crop by ratio

[](#crop-by-ratio)

Crops the image to the specified aspect ratio, cutting off the rest of the image.

Ratio are two numbers greater than zero separated by :. Ratio is the quotient from the division of these numbers.

Alignment can be set in pixels and percentages but also a shortcut can be used. The possible values are: `top`, `center`, `bottom`, `left`, `right`. If alignment is not specified, `center` value is used.

```
// Using percentages and a shortcut.
$url = $transformation->cropByRatio(ratio: '4:3', offsetX: 'bottom');
// https://example.com/cdn/.../-/crop/4:3/bottom/

// Using percentage in combination with pixels.
$url = $transformation->cropByRatio(ratio: '4:3', offsetX: '50p', offsetY: 240);
// https://example.com/cdn/.../-/crop/4:3/50p,240/
```

### Enhance

[](#enhance)

Auto-enhances an image by performing the following operations: auto levels, auto contrast, and saturation sharpening.

Strength must be a number between 0 and 100. Default value is 50.

```
$url = $transformation->enhance(strength: 50);
// https://example.com/cdn/.../-/enhance/50/
```

### Filter

[](#filter)

Applies one of predefined photo filters by its name. The way your images look affects their engagement rates. You apply filters thus providing beautiful images consistent across content pieces you publish.

The name parameter should be one of the following: `adaris`, `briaril`, `calarel`, `carris`, `cynarel`, `cyren`, `elmet`, `elonni`, `enzana`, `erydark`, `fenralan`, `ferand`, `galen`, `gavin`, `gethriel`, `iorill`, `iothari`, `iselva`, `jadis`, `lavra`, `misiara`, `namala`, `nerion`, `nethari`, `pamaya`, `sarnar`, `sedis`, `sewen`, `sorahel`, `sorlen`, `tarian`, `thellassan`, `varriel`, `varven`, `vevera`, `virkas`, `yedis`, `yllara`, `zatvel`, `zevcen`.

The amount parameter must be a number between -100 and 200.

```
$url = $transformation->filter(name: 'adaris', value: 50);
// https://example.com/cdn/.../-/filter/adaris/50/
```

### Flip

[](#flip)

Flips images.

```
$url = $transformation->flip();
// https://example.com/cdn/.../-/flip/
```

### Format

[](#format)

Converts an image to one of the following formats: `jpg`, `png`, `webp`, `auto`.

```
$url = $transformation->format(format: 'jpeg');
// https://example.com/cdn/.../-/format/jpg/
```

### Grayscale

[](#grayscale)

Desaturates images. The operation has no additional parameters and simply produces a grayscale image output when applied.

```
$url = $transformation->grayscale();
// https://example.com/cdn/.../-/grayscale/
```

### ICC profile size threshold

[](#icc-profile-size-threshold)

The operation defines which RGB color profile sizes will be considered “small” and “large” when using srgb in `fast` or `icc` modes. The `number` stands for the ICC profile size in kilobytes.

The default value is 10 (10240 bytes). Most of the common RGB profile sizes (sRGB, Display P3, ProPhoto, Adobe RGB, Apple RGB) are below the threshold.

> Please note, that because this transformation should always be used in combination with [`convertToSRGB()`](#convert-to-srgb) its method should be called **after** `convertToSRGB()`. Otherwise the ICC profile size threshold gets overwritten by the `convertToSRGB()` transformation.

```
$url = $transformation->convertToSRGB(profile: 'fast')->iccProfileSizeThreshold(number: 10);
// https://example.com/cdn/.../-/max_icc_size/10/srgb/fast/
```

### Invert

[](#invert)

Inverts images rendering a 'negative' of the input.

```
$url = $transformation->invert();
// https://example.com/cdn/.../-/invert/
```

### Miror

[](#miror)

Mirrors images.

```
$url = $transformation->mirror();
// https://example.com/cdn/.../-/mirror/
```

### Overlay

[](#overlay)

The overlay operation allows to layer images one over another. One of the most common use cases here are watermarks: semi-transparent images layered over opaque ones to complicate their unauthorized usage, etc.

> Every overlay parameter is optional and can be omitted. However, the order of parameter URL directives should be preserved. For example, if you want to use `coordinateX` parameter, you should also specify `width` and `height` parameters. Also note that the `opacity` parameter should be specified with percentages.

```
$uuidOverlay = 'e6b0c1c0-1b1a-4b1a-9b1a-1b1a1b1a1b1a';

$url = $transformation->overlay(
  uuid: $uuidOverlay,
  width: 150,
  height: 150,
  coordinateX: 200,
  coordinateY: 300,
  opacity: '25p'
)->getUrl();
// https://example.com/cdn/.../-/overlay/e6b0c1c0-1b1a-4b1a-9b1a-1b1a1b1a1b1a/150x150/200,300/25p/
```

### Preview

[](#preview)

Downscales an image proportionally to fit the given width and height in pixels.

```
$url = $transformation->preview(width: 100, height: 100);
// https://example.com/cdn/.../-/preview/100x100/
```

### Progressive

[](#progressive)

Returns a progressive image. In progressive images, data are compressed in multiple passes of progressively higher detail. The operation does not affect non-JPEG images; does not force image formats to JPEG.

```
$url = $transformation->progressive(true);
// https://example.com/cdn/.../-/progressive/yes/

$url = $transformation->progressive(false);
// https://example.com/cdn/.../-/progressive/no/
```

### Quality

[](#quality)

Sets output JPEG and WebP quality. Since actual settings vary from codec to codec, and more importantly, from format to format, we provide five simple tiers and two automatic values which suits most cases of image distribution and are consistent.

Quality must be one of the following values: `smart`, `smart_retina`, `normal`, `better`, `best`, `lighter`, `lightest`.

```
$url = $transformation->quality(quality: 'smart');
// https://example.com/cdn/.../-/quality/smart/
```

### Rasterize

[](#rasterize)

Rasterize SVG images.

```
$url = $transformation->rasterize();
// https://example.com/cdn/.../-/rasterize/
```

### Resize

[](#resize)

Resizes an image to one or two dimensions. When you set both width and height explicitly, it may result in a distorted image. If you specify either side, this operation will preserve the original aspect ratio and resize the image accordingly. Mode should be one of the following values: `on`, `off`, `fill`.

```
// Using width, height, stretch and 'fill' mode.
$url = $transformation->resize(width: 100, height: null, stretch: true, mode: 'fill');
// https://example.com/cdn/.../-/resize/100x/stretch/fill/

// Using only height, no stretch and no mode.
$url = $transformations->resize(width: null, height: 250, stretch: false);
// https://example.com/cdn/.../-/resize/250x/
```

### Rotate

[](#rotate)

Right-angle image rotation, counterclockwise. The value of angle must be a multiple of 90.

```
$url = $transformation->rotate(angle: 180);
// https://example.com/cdn/.../-/rotate/180/
```

### Scale crop

[](#scale-crop)

Scales an image until it fully covers the specified dimensions; the rest gets cropped. Mostly used to place images with various dimensions into placeholders (e.g., square shaped).

Dimensions must be set in pixels.

Alignment must be set in percentages or shortcut. The possible values are: `top`, `center`, `bottom`, `left`, `right`. If alignment is not specified, `0,0` value is used.

```
// Using percentages.
$url = $transformation->scaleCrop(width: 100, height: 100, offsetX: '30p', offsetY: '50p');
// https://example.com/cdn/.../-/scale_crop/100x100/30p,50p/

// Using shortcut.
$url = $transformation->scaleCrop(width: 100, height: 100, offsetX: 'bottom');
// https://example.com/cdn/../-/scale_crop/100x100/bottom/
```

### Set fill

[](#set-fill)

Sets the fill color used with crop, stretch or when converting an alpha channel enabled image to JPEG.

Color must be a hex color code **without using the hashtag**.

```
$url = $transformation->setFill(color: 'ff0000');
// https://example.com/cdn/.../-/setfill/ff0000/
```

### Sharpen

[](#sharpen)

Sharpens an image, might be especially useful with images that were subjected to downscaling. strength can be in the range from 0 to 20 and defaults to the value of 5.

```
$url = $transformation->sharpen(strength: 20);
// https://example.com/cdn/.../-/sharp/20/
```

### Smart crop

[](#smart-crop)

Switching the crop type to one of the smart modes enables the content-aware mechanics. Uploadcare applies AI-based algorithms to detect faces and other visually sensible objects to crop the background and not the main object.

Dimensions must be set in pixels.

Type must be one of the following values: `smart`, `smart_faces_objects`, `smart_faces`, `smart_objects`, `smart_faces_points`, `smart_points`, `smart_objects_faces_points`, `smart_objects_points` or `smart_objects_faces`.

Aligment must be set in percentages or shortcut. The possible values are: `top`, `center`, `bottom`, `left`, `right`. If alignment is not specified, `0,0` value is used.

```
// Using percentages.
$url = $transformation->smartCrop(width: 100, height: 100, type: 'smart_faces_objects', offsetX: '30p', offsetY: '50p');
// https://example.com/cdn/.../-/scale_crop/100x100/smart_faces_objects/30p,50p/

// Using shortcut.
$url = $transformation->smartCrop(width: 100, height: 100, type: 'smart_faces_objects', offsetX: 'right');
// https://example.com/cdn/.../-/scale_crop/100x100/smart_faces_objects/right/
```

### Smart resize

[](#smart-resize)

Content-aware resize helps retaining original proportions of faces and other visually sensible objects while resizing the rest of the image using intelligent algorithms.

```
$url = $transformation->smartResize(width: 500, height: 500);
// https://example.com/cdn/.../-/smart_resize/500x500/
```

### Zoom objects

[](#zoom-objects)

Zoom objects operation is best suited for images with solid or uniform backgrounds.

Zoom must be a number between 1 and 100.

```
$url = $transformation->zoomObjects(zoom: 50);
// https://example.com/cdn/.../-/zoom_objects/50/
```

Testing
-------

[](#testing)

```
./-/vendor/bin/pest
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../-/../-/security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Bas van Dinther](https://github.com/baspa)
- [Mark van Eijk](https://github.com/markvaneijk)
- [All Contributors](../-/../-/contributors)

License
-------

[](#license)

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

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance74

Regular maintenance activity

Popularity21

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity73

Established project with proven stability

 Bus Factor1

Top contributor holds 78.2% 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 ~45 days

Recently: every ~1 days

Total

25

Last Release

271d ago

Major Versions

v0.4.0 → v1.0.02023-06-15

PHP version history (3 changes)v0.1.0PHP ^8.0

v0.1.1PHP ^8.1

v1.1.0PHP ^8.1|^8.2|^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/7c6a425dc8645907a118a007438172d58c2016773f54ab3a834beff172632f13?d=identicon)[ux](/maintainers/ux)

---

Top Contributors

[![Baspa](https://avatars.githubusercontent.com/u/10845460?v=4)](https://github.com/Baspa "Baspa (309 commits)")[![markvaneijk](https://avatars.githubusercontent.com/u/1925388?v=4)](https://github.com/markvaneijk "markvaneijk (47 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (26 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (11 commits)")[![Ynitial](https://avatars.githubusercontent.com/u/35238373?v=4)](https://github.com/Ynitial "Ynitial (2 commits)")

---

Tags

filesimage-manipulationimage-processingphpuploadcareuploadsphp-uploadcare-transformationsbackstage

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/backstage-php-uploadcare-transformations/health.svg)

```
[![Health](https://phpackages.com/badges/backstage-php-uploadcare-transformations/health.svg)](https://phpackages.com/packages/backstage-php-uploadcare-transformations)
```

###  Alternatives

[milon/barcode

Barcode generator like Qr Code, PDF417, C39, C39+, C39E, C39E+, C93, S25, S25+, I25, I25+, C128, C128A, C128B, C128C, 2-Digits UPC-Based Extention, 5-Digits UPC-Based Extention, EAN 8, EAN 13, UPC-A, UPC-E, MSI (Variation of Plessey code)

1.5k13.3M39](/packages/milon-barcode)[bkwld/croppa

Image thumbnail creation through specially formatted URLs for Laravel

510496.0k22](/packages/bkwld-croppa)[goat1000/svggraph

Generates SVG graphs

132849.6k3](/packages/goat1000-svggraph)[vormkracht10/php-uploadcare-transformations

Composer package for generating URLs using Uploadcare for image transformations and processing.

1413.1k](/packages/vormkracht10-php-uploadcare-transformations)[cohensive/embed

Media Embed (for Laravel or as a standalone).

120370.4k](/packages/cohensive-embed)[vormkracht10/laravel-open-graph-image

Laravel package to generate dynamic Open Graph images

7217.7k](/packages/vormkracht10-laravel-open-graph-image)

PHPackages © 2026

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