> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP image transformations


After you or your users have uploaded image assets to Cloudinary, you can deliver them via dynamic URLs. You can include instructions in your dynamic URLs that tell Cloudinary to transform your assets using a set of transformation parameters. All transformations are performed automatically in the cloud and your transformed assets are automatically optimized before they are routed through a fast CDN to the end user for optimal user experience.

For example, you can resize and crop, add overlay images, blur or pixelate faces, apply a large variety of special effects and filters, and apply settings to optimize your images and to deliver them responsively.

Cloudinary's PHP library simplifies the generation of transformation URLs for easy embedding of assets in your PHP application.

See also: [PHP video transformation](php_video_manipulation)

## Syntax overview

The PHP SDK provides a more intuitive coding experience for transforming an asset:

* The SDK supports an action-based syntax, designed to make building delivery URLs and transformations more logical and discoverable. 
* When compiled to the final delivery URL, each action represents a different [transformation component](image_transformations#chained_transformations).
* Allows discovering the available options from within your development environment, and ensures that only options that are supported can be used together.

![SDK2 transformation structure](https://res.cloudinary.com/demo/image/upload/q_auto,f_auto,dpr_2/docs/php2_syntax "with_url: false, with_code: false, width: 700")

[//]: # (source file: https://docs.google.com/presentation/d/1uSIigbItua-GFIY9Ppd0btXC7F1juyDACveokLlXlSw/edit?usp=sharing)

* **ActionGroup**: An `ActionGroup` represents a directive to Cloudinary on how to transform a specific aspect of an asset (e.g., `effect`, `adjust` or `resize`). 
* **Action**: The `Action` defines the specific Action to apply (e.g., `Effect::outline()`, `Adjust::replaceColor()` or `Resize::crop()`). 
* **Qualifier**: `Qualifiers` further define how to apply an Action (e.g., `tolerance` qualifies the `Adjust::replaceColor` Action with the tolerance threshold of the input color to be replaced `17`). Some Actions also have a required qualifier which is then given as part of the action method (e.g., `Adjust::replaceColor(Color::GREEN)` to specify the color to apply).

The output of each `Action` is a complete transformation component in the URL. If there are multiple actions, then each transformation component is separated by slashes in the URL. For example, the syntax example above would generate a URL similar to the following:

```
https://res.cloudinary.com/demo/image/upload/e_replace_color:green:17/mypic.jpg
```

## Deliver and transform images

You can deliver your images using methods the generate image tags or via direct URL-building directives. 

### The ImageTag method

You can add images to your PHP view using Cloudinary's `ImageTag` helper method. This method generates the full image resource URL based on the given transformation parameters and adds the image tag to your HTML code:

```php
use Cloudinary\Cloudinary;

$cld = new Cloudinary();
$cld->ImageTag('sample');
```

The code above generates the following HTML image tag:

```html
<img src="https://res.cloudinary.com/demo/image/upload/sample">
```

You can also include actions in the request, for example, to deliver an image padded to a width of 400 pixels:
 
```php
use Cloudinary\Transformation\Resize;

$cld->ImageTag('sample')->resize(Resize::pad(400));
```

> **NOTE**: You also need to include the Group classes you use (e.g. `Resize` in the example above).

For a full list of the available ImageTag methods, see the [PHP reference](https://cloudinary.com/documentation/sdks/php/Cloudinary/Tag/ImageTag.html).

> **TIP**:
>
> In general, when using an SDK, you will probably take advantage of the SDK parameter names for improved readability and maintenance of your code. However, you can also optionally add any transformation in [URL syntax](transformation_reference) using the **addTransformation** method.
> For example:
> ```php
$cld->ImageTag('sample')->addTransformation('c_scale,w_400/e_cartoonify');
```

### Chaining transformation actions

Cloudinary supports powerful transformations. You can even combine multiple transformation actions together as part of a single transformation request, e.g. resize an image and add a border. In certain cases you may want to perform additional transformations on the result of the previous transformation action. To do that, you can use chained transformation actions. The following example first fills the image within a 250px square, then rounds the result to a circle, and finally delivers the image in the optimal transparent format:

![3 chained transformations applied to an image](https://res.cloudinary.com/demo/image/upload/ar_1.0,c_fill,w_250/r_max/f_auto/livingroom-yellow-chair.png "disable_all_tab:true, frameworks:php_2")

```php
(new ImageTag('livingroom-yellow-chair.png'))
	->resize(Resize::fill()->width(250)
->aspectRatio(1.0))
	->roundCorners(RoundCorners::max())
	->delivery(Delivery::format(
	Format::auto()));
```

The following example applies 4 chained transformations: fill to a 250*400px portrait, then rotate the result by 20 degrees, then add a brown outline to the rotated image, and optimize the resulting image to deliver with the best compression that gives good visual quality and in the optimal transparent format:

![4 chained transformations applied to an image](https://res.cloudinary.com/demo/image/upload/c_fill,h_400,w_250/a_20/e_outline,co_brown/q_auto/f_auto/kitchen-island.png "thumb:h_350,dpr_2, height:350, disable_all_tab:true, frameworks:php_2")

```php
(new ImageTag('kitchen-island.png'))
	->resize(Resize::fill()->width(250)
->height(400))
	->rotate(Rotate::byAngle(20))
	->effect(Effect::outline()
	->color(Color::BROWN)
	)
	->delivery(Delivery::quality(
	Quality::auto()))
	->delivery(Delivery::format(
	Format::auto()));
```

For more information on image transformations, see [Apply common image transformations](#apply_common_image_transformations).

### Direct URL building

The `ImageTag` method described above generates an HTML image tag. In certain conditions, you might want to generate a transformation URL directly, without the containing image tag. To return only the URL, use the `Image` helper method, and call the `toUrl()` method. Here are few examples:

```php
$cld->Image('sample.jpg')
  ->resize(Resize::fill(100,150))->toUrl();       
// Output: "https://res.cloudinary.com/demo/image/upload/c_fill,h_150,w_100/sample.jpg"

$cld->Image('sample.png') 
  ->resize(Resize::scale(200, 200))
  ->effect(Effect::sepia())->toUrl();
// Output: "https://res.cloudinary.com/demo/image/upload/c_scale,h_200,w_200/e_sepia/sample.png"
```

> **NOTE**: Instead of calling the `toUrl()`method you also have the option to cast the image method to a string `(string)$cld->Image()`, or place the method inside a string `"{$cld->Image()}"`

## Apply common image transformations

This section provides an overview and examples of the following commonly used image transformation features, along with links to more detailed documentation on these features:

- [Syntax overview](#syntax_overview)
- [Deliver and transform images](#deliver_and_transform_images)
  - [The ImageTag method](#the_imagetag_method)
  - [Chaining transformation actions](#chaining_transformation_actions)
  - [Direct URL building](#direct_url_building)
- [Apply common image transformations](#apply_common_image_transformations)
  - [Resizing and cropping](#resizing_and_cropping)
  - [Converting to another image format](#converting_to_another_image_format)
  - [Applying image effects and filters](#applying_image_effects_and_filters)
  - [Adding text and image overlays](#adding_text_and_image_overlays)
  - [Image optimizations](#image_optimizations)
  - [Responsive image settings](#responsive_image_settings)

Keep in mind that this section is only intended to introduce you to the basics of using image transformations with PHP. 

For comprehensive explanations of how to implement a wide variety of transformations, see [Image transformations](image_transformations).
For a full list of all supported image transformations and their usage, see the [Transformation URL API Reference](transformation_reference).

### Resizing and cropping

There are a variety of different ways to resize and/or crop your images, and to control the area of the image that is preserved during a crop. 

The following example uses the `fill` cropping method to generate and deliver an image that completely fills the requested 200x200 size while retaining the original aspect ratio. It uses face detection gravity to ensure that all the faces in the image are retained and centered when the image is cropped:

![Cropping](https://res.cloudinary.com/demo/image/upload/w_200,h_200,c_fill,g_faces/family_bench.jpg "secure: true, disable_all_tab: true, with_url: false, with_image: false, frameworks:php_2")

```php
(new ImageTag('family_bench.jpg'))
	->resize(Resize::fill()->width(200)
->height(200)
	->gravity(
	Gravity::focusOn(
	FocusOn::faces()))
	);
```

Original image

Fill cropping with 'faces' gravity

You can also use automatic gravity to determine what to keep in the crop automatically.

![Crop an image using automatic gravity in PHP](https://res.cloudinary.com/demo/image/upload/w_200,h_300,c_fill,g_auto/basketball_in_net.jpg "disable_all_tab: true, with_image:false, with_url:false, frameworks:php_2" )

Original image

Fill cropping with 'auto' gravity

For details on all resizing and cropping options, see [resizing and cropping images](resizing_and_cropping).

### Converting to another image format

You can deliver any image uploaded to Cloudinary in essentially any image format. There are three main ways to convert and deliver in another format:

* Specify the image's public ID with the desired extension. 
* Explicitly setting the desired format using the `fetch_format` parameter. 
* Using the `auto` fetch_format to instruct Cloudinary to deliver the image in the most optimized format for each browser that requests it.

For example:

1. Deliver a .jpg file in .gif format: 
  ![Deliver a .jpg file as a .gif](https://res.cloudinary.com/demo/image/upload/sample.gif "disable_all_tab: true, with_url:false, with_image:false, frameworks:php_2")

```php
(new ImageTag('sample.gif'));
```
2. Let Cloudinary select the optimal format for each browser. For example, in Chrome, this image may deliver in **.avif** or **.webp** format (depending on your product environment setup):
  ![Let Cloudinary select the optimal format to deliver for each browser.](https://res.cloudinary.com/demo/image/upload/c_scale,w_350/f_auto/cloud_castle.jpg  "disable_all_tab: true, with_url:false, with_image:false, frameworks:php_2")

```php
(new ImageTag('cloud_castle.jpg'))
	->resize(Resize::scale()->width(350))
	->delivery(Delivery::format(
	Format::auto()));
```
  The above code generates a URL with the `f_auto` parameter:
  ![Let Cloudinary select the optimal format to deliver for each browser.](https://res.cloudinary.com/demo/image/upload/c_scale,w_350/f_auto/cloud_castle.jpg  "with_code:false, with_url:true, with_image:false")

For more details, see:

* [Delivering images in different formats](image_transformations#delivering_in_a_different_format)
* [Automatic format selection (f_auto)](image_optimization#automatic_format_selection_f_auto)
* [Tips and considerations for using f_auto](image_optimization#tips_and_considerations_for_using_f_auto)

For more details see [Image format support](image_transformations#image_format_support).

### Applying image effects and filters

You can select from a large selection of image effects, enhancements, and filters to apply to your images. The available effects include a variety of color balance and level effects, tinting, blurring, pixelating, sharpening, automatic improvement effects, artistic filters, image and text overlays, distortion and shape changing effects, outlines, backgrounds, shadows, and more.

For example, the code below applies a cartoonify effect, rounding corners effect, and background color effect (and then scales the image down to a height of 300 pixels).

![An image with several transformation effects](https://res.cloudinary.com/demo/image/upload/e_cartoonify/r_max/b_lightblue/h_300/actor.jpg "secure: true, disable_all_tab: true, with_url: false, frameworks:php_2")

```php
(new ImageTag('actor.jpg'))
	->effect(Effect::cartoonify())
	->roundCorners(RoundCorners::max())
	->backgroundColor(Color::LIGHTBLUE)
	->resize(Resize::scale()->height(300));
```

For more details on the available image effects and filters, see [Visual image effects and enhancements](effects_and_artistic_enhancements)

### Adding text and image overlays

You can add images and text as overlays on your main image. You can apply the same types of transformations on your overlay images as you can with any image and you can use gravity settings or x and y coordinates to control the location of the overlays. You can also apply a variety of transformations on text, such color, font, size, rotation, and more.

For example, the code below overlays a couple's photo on a mug image. The overlay photo is cropped using face detection with adjusted color saturation and a vignette effect applied. The word love is added in a brown, fancy font and placed to fit the design.  Additionally, the final image is cropped and the corners are rounded.

![An image with many transformations and overlays applied](https://res.cloudinary.com/demo/image/upload/w_400,h_250,c_fill,g_south/l_nice_couple,w_1.3,h_1.3,g_faces,c_crop,fl_region_relative/e_saturation:50/e_vignette/fl_layer_apply,w_100,r_max,g_center,y_15,x_-20/l_text:Cookie_23_bold:Love,co_rgb:744700/fl_layer_apply,x_-23,y_50/c_crop,w_300,h_250,x_30/r_60/coffee_cup.png "disable_all_tab: true, frameworks:php_2, with_url:false")

```php
(new ImageTag('coffee_cup.png'))
	->resize(Resize::fill()->width(400)
->height(250)
	->gravity(
	Gravity::compass(
	Compass::south()))
	)
	->overlay(Overlay::source(
	Source::image("nice_couple")
	->transformation((new Transformation())
	->resize(Resize::crop()->width(1.3)
->height(1.3)
	->gravity(
	Gravity::focusOn(
	FocusOn::faces()))
	->regionRelative()
	)
	->adjust(Adjust::saturation()->level(50))
	->effect(Effect::vignette())
	->resize(Resize::scale()->width(100))
	->roundCorners(RoundCorners::max()))
	)
	->position((new Position())
	->gravity(
	Gravity::compass(
	Compass::center()))
->offsetX(-20)
->offsetY(15))
	)
	->overlay(Overlay::source(
	Source::text("Love",(new TextStyle("Cookie",23))
	->fontWeight(
	FontWeight::bold())
	)
	->textColor(Color::rgb("744700"))
	)
	->position((new Position())->offsetX(-23)
->offsetY(50))
	)
	->resize(Resize::crop()->width(300)
->height(250)
->x(30))
	->roundCorners(RoundCorners::byRadius(60));
```

### Image optimizations

By default, Cloudinary automatically performs certain optimizations on all transformed images. There are also a number of additional features that enable you to further optimize the images you use in your application. These include optimizations to image quality, format, and size, among others.

For example, you can use the `auto` value for the `fetch_format` and `quality` attributes to automatically deliver the image in the format and quality that minimize file size while meeting the required quality level. In addition, resize the image to make it even lighter. Below, these parameters are applied, resulting in a 25.66 KB AVIF file (in Chrome) instead of a 1.34 MB JPG with no visible change in quality. 

![Efficient file size optimization using auto format and auto quality features](https://res.cloudinary.com/demo/image/upload/w_500/f_auto,q_auto/pond_reflect.jpg "disable_all_tab: true, with_url:false, frameworks:php_2")

```php
(new ImageTag('pond_reflect.jpg'))
	->resize(Resize::scale()->width(500))
	->delivery(Delivery::format(
	Format::auto()))
	->delivery(Delivery::quality(
	Quality::auto()));
```

For an in-depth review of the many ways you can optimize your images, see [Image optimization](image_optimization)

### Responsive image settings

Responsive web design is a method of designing websites to provide an optimal viewing experience to users, irrespective of the device, viewport size, orientation, or resolution used to view it. Ensuring that optimal experience means you should avoid sending high resolution images that get resized client side, with significant bandwidth waste for users of small displays. Instead, you should always deliver the right size image for each device and screen size. 

For example, you can ensure that each user receives images at the size and device pixel ratio (dpr) that fit their device using the `auto` value for the `dpr` and `width` attributes. The `auto` value is replaced with actual values on the client side based on the screen properties and viewport width:

```php
$myTag = $cld->ImageTag('myphoto')
    ->resize(Resize::scale()->width('auto'))
    ->dpr('auto')
    ->rotate(Rotate::byAngle(20))
    ->border(Border::solid()->width(3)->color(Color::RED))
    ->roundCorners(RoundCorners::max())
    ->effect(Effect::artisticFilter(ArtisticFilter::HOKUSAI));
$myTag->config->tag->responsive = true;
$myTag->config->tag->responsivePlaceholder = 'blank';
```
 
Cloudinary offers several options for simplifying the complexity of delivering responsive images. For a detailed guide on how to implement these options, see [Responsive images](responsive_images).

> **See also**:
>
> * Get an overview of the PHP SDK, and the various [configuration](php_integration) options.

> * Learn more about [uploading images and videos](php_image_and_video_upload) using the PHP SDK.    

> * See examples of powerful [video](php_video_manipulation) transformations using PHP code and see our [image transformations](image_transformations) and [video transformation](video_manipulation_and_delivery) docs.   

> * Check out Cloudinary's [asset management](php_asset_administration) capabilities, for example, renaming and deleting assets, adding tags and metadata to assets, and searching for assets.