---
title: "Image"
version: "5.19"
---

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

# Image

## Overview

The `Phalcon\Image` namespace exposes an adapter that offers image manipulating functionality. These adapters are designed to allow multiple operations to be performed on the same image.

## Adapters

This component uses adapters that offer methods to manipulate images. You can create your own adapter using the [Phalcon\Image\Adapter\AdapterInterface][image-adapter-adapterinterface].

| Class                                                  | Description                                       |
|--------------------------------------------------------|---------------------------------------------------|
| [Phalcon\Image\Adapter\Gd][image-adapter-gd]           | Requires the [GD PHP extension][gd]               |
| [Phalcon\Image\Adapter\Imagick][image-adapter-imagick] | Requires the [ImageMagick PHP extension][imagick] |

## Constants

[Phalcon\Image\Enum][image-enum] holds constants for image resizing and flipping. The available constants are:

**Resize**

- `AUTO`
- `HEIGHT`
- `INVERSE`
- `NONE`
- `PRECISE`
- `TENSILE`
- `WIDTH`

**Flip**

- `HORIZONTAL`
- `VERTICAL`

## Supported images (GD)

- IMAGETYPE_GIF
- IMAGETYPE_JPEG
- IMAGETYPE_JPEG2000
- IMAGETYPE_PNG
- IMAGETYPE_WEBP
- IMAGETYPE_WBMP
- IMAGETYPE_XBM

## Getters

Each adapter offers getters to provide information about the component:

| Method                  | Description                                       |
|-------------------------|---------------------------------------------------|
| `getHeight(): int`      | Returns the image height                          |
| `getImage(): mixed`     | Returns the image                                 |
| `getMime(): string`     | Returns the image mime type                       |
| `getRealpath(): string` | Returns the real path where the image is located  |
| `getType(): int`        | Returns the image type (This is driver dependent) |
| `getWidth(): int`       | Returns the image width                           | 

## GD

[Phalcon\Image\Adapter\Gd][image-adapter-gd] utilizes the [GD PHP extension][gd]. In order for you to use this adapter, the extension has to be present in your system. The adapter offers all the methods described below in the operations section.

## Imagick

[Phalcon\Image\Adapter\Imagick][image-adapter-imagick] utilizes the [ImageMagick PHP extension][imagick]. In order for you to use this adapter, the extension has to be present in your system. The adapter offers all the methods described below in the operations section.

## Blank Images

Each adapter can create a blank, in-memory canvas instead of loading a file. Call the static `create()` method with the width and height in pixels. It returns a ready-to-use adapter that you can draw on, composite onto, and save.

- `Phalcon\Image\Adapter\Gd::create()` creates a true-color canvas
- `Phalcon\Image\Adapter\Imagick::create()` creates a transparent canvas

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = Gd::create(640, 480);

$image->background('#ffffff');

$image->save('canvas.png');
```

The constructor also creates a blank canvas when the supplied file does not exist and both a width and a height are given. That dual behavior is kept for backward compatibility but is slated for removal in a future major version; use `create()` for new code.

```php
<?php

use Phalcon\Image\Adapter\Gd;

// Creates a blank canvas because 'canvas.png' does not exist
$image = new Gd('canvas.png', 640, 480);
```

## Operations

### `background()`

Sets the background color for the image. The available parameters are:

| Parameter       | Description                            |
|-----------------|----------------------------------------|
| `string $color` | the color in hex format                |
| `int $opacity`  | the opacity (optional - default `100`) |

The color must be a valid hex string: `#rgb`, `rgb`, `#rrggbb`, or `rrggbb`. An invalid value throws `Phalcon\Image\Exceptions\InvalidColor`.

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->background('#000033', 70);

$image->save('background-image.jpg');
```

### `blur()`

Blurs the image. The passed integer parameter specifies the radius for the blur operation. The range is between 0 (no effect) and 100 (very blurry):

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->blur(50);

$image->save('blur-image.jpg');
```

### `crop()`

You can crop images programmatically. The `crop()` method accepts the following parameters:

| Parameter      | Description             |
|----------------|-------------------------|
| `int $width`   | the width               |
| `int $height`  | the height              |
| `int $offsetX` | the X offset (optional) |
| `int $offsetY` | the Y offset (optional) |

The following example crops 100px by 100px from the center of the image:

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$width   = 100;
$height  = 100;
$offsetX = ($image->getWidth() - $width) / 2;
$offsetY = ($image->getHeight() - $height) / 2;

$image->crop($width, $height, $offsetX, $offsetY);

$image->save('crop-image.jpg');
```

### `flip()`

You can flip an image horizontally or vertically. The `flip()` method accepts an integer, signifying the direction. You can use the constants for this operation:

- `Phalcon\Image\Enum::HORIZONTAL`
- `Phalcon\Image\Enum::VERTICAL`

```php
<?php

use Phalcon\Image\Adapter\Gd;
use Phalcon\Image\Enum;

$image = new Gd('image.jpg');

$image->flip(Enum::HORIZONTAL);

$image->save('flip-image.jpg');
```

### `liquidRescale()`

This method is only available in the [Phalcon\Image\Imagick][image-adapter-imagick] adapter. It uses the [liquid][imagick-liquidrescale] rescaling method to rescale the image. The method accepts the following parameters:

| Parameter       | Description                                                                                                     |
|-----------------|-----------------------------------------------------------------------------------------------------------------|
| `int $width`    | the new width                                                                                                   | 
| `int $height`   | the new height                                                                                                  |
| `int $deltaX`   | How much the seam can traverse on x-axis. Passing `0` causes the seams to be straight. (optional - default `0`) |
| `int $rigidity` | Introduces a bias for non-straight seams. (optional - default `0`)                                              |

```php
<?php

use Phalcon\Image\Adapter\Imagick;

$image = new Imagick('image.jpg');

$image->liquidRescale(500, 200, 3, 25);

$image->save('liquidrescale-image.jpg');
```

### `mask()`

Creates a composite image from two images. Accepts the first image as a parameter.

The mask is read through its `render()` output, so a mask produced by a different adapter (for example an Imagick mask applied to a GD image) composites correctly. Each call performs one encode/decode round trip.

```php
<?php

use Phalcon\Image\Adapter\Gd;

$front = new Gd('front.jpg');
$back  = new Gd('back.jpg');

$front->mask($front);

$front->save('mask-image.jpg');
```

### `pixelate()`

Adds pixelation to the image. The method accepts a single integer parameter. The higher the number, the more pixelated the image becomes:

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->pixelate(10);

$image->save('pixelate-image.jpg');
```

### `reflection()`

Adds reflection to the image. The method accepts the following parameters:

| Parameter      | Description                                            |
|----------------|--------------------------------------------------------|
| `int $height`  | the height                                             |
| `int $opacity` | the opacity (optional - default `100`)                 |
| `bool $fadeIn` | whether to fade in or not (optional - default `false`) |

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->reflection(100, 75, true);

$image->save('reflection-image.jpg');
```

### `render()`

Renders the image and returns it back as a binary string. The method accepts the following parameters:

| Method         | Description                                         |
|----------------|-----------------------------------------------------|
| `string $ext`  | the extension (optional)                            |
| `int $quality` | the quality of the image (optional - default `100`) |

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

// ....

echo $image->render('jpg', 90);
```

### `resize()`

Resize the image based on the passed parameters. The method accepts the following parameters:

| Parameter     | Description                                              |
|---------------|----------------------------------------------------------|
| `int $width`  | the width (optional)                                     |
| `int $height` | the height (optional)                                    |
| `int $master` | constant signifying the resizing method (default `AUTO`) |

**Constants**

- `Phalcon\Image\Enum::AUTO`
- `Phalcon\Image\Enum::HEIGHT`
- `Phalcon\Image\Enum::INVERSE`
- `Phalcon\Image\Enum::NONE`
- `Phalcon\Image\Enum::PRECISE`
- `Phalcon\Image\Enum::TENSILE`
- `Phalcon\Image\Enum::WIDTH`

If any of the parameters are not correct, a [Phalcon\Image\Exception][image-exception] will be thrown.

**HEIGHT**

The width will automatically be generated to keep the proportions the same; if you specify a width, it will be ignored.

```php
<?php

use Phalcon\Image\Adapter\Gd;
use Phalcon\Image\Enum;

$image = new Gd('image.jpg');

$image->resize(null, 300, Enum::HEIGHT);

$image->save('resize-height-image.jpg');
```

**INVERSE**

Resizes and inverts the width and height passed

```php
<?php

use Phalcon\Image\Adapter\Gd;
use Phalcon\Image\Enum;

$image = new Gd('image.jpg');

$image->resize(400, 200, Enum::INVERSE);

$image->save('resize-inverse-image.jpg');
```

**NONE**

- The `NONE` constant ignores the original image's ratio.
- Neither width nor height are required.
- If a dimension is not specified, the original dimension will be used.
- If the new proportions differ from the original proportions, the image may be distorted and stretched.

```php
<?php

use Phalcon\Image\Adapter\Gd;
use Phalcon\Image\Enum;

$image = new Gd('image.jpg');

$image->resize(400, 200, Enum::NONE);

$image->save('resize-none-image.jpg');
```

**TENSILE**

- Similar to the `NONE` constant, the `TENSILE` constant ignores the original image's ratio.
- Both width and height are required.
- If the new proportions differ from the original proportions, the image may be distorted and stretched.

```php
<?php

use Phalcon\Image\Adapter\Gd;
use Phalcon\Image\Enum;

$image = new Gd('image.jpg');

$image->resize(400, 200, Enum::TENSILE);

$image->save('resize-tensile-image.jpg');
```

**WIDTH**

The height will automatically be generated to keep the proportions the same; if you specify a height, it will be ignored.

```php
<?php

use Phalcon\Image\Adapter\Gd;
use Phalcon\Image\Enum;

$image = new Gd('image.jpg');

$image->resize(300, null, Enum::WIDTH);

$image->save('resize-width-image.jpg');
```

### `rotate()`

Rotates an image based on the given degrees. Positive numbers rotate the image clockwise while negative counterclockwise.

The following example rotates an image by 90 degrees clockwise

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->rotate(90);

$image->save('rotate-image.jpg');
```

### `save()`

After manipulating your image, you will most likely want to save it. If you wish to get the result of the manipulations back as a string, you can use the `render()` method.

The `save()` method accepts the filename and quality as parameters:

| Property       | Description                                        |
|----------------|----------------------------------------------------|
| `string $file` | the target file name (optional)                    |
| `int $quality` | the quality of the image (optional - default `-1`) |

If a file name is not specified, the manipulated image will overwrite the original image.

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->rotate(90);

$image->save();
```

When specifying a file name, the manipulated image will be saved with that name, leaving the original image unchanged.

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->rotate(90);

$image->save('rotate-image.jpg');
```

You can also change the format of the image using a different extension. This functionality depends on the adapter you are working with.

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->rotate(90);

$image->save('rotate-image.png');
```

When saving as a JPEG, you can also specify the quality as the second parameter:

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->rotate(90);

$image->save('rotate-image.jpg', 90);
```

### `sharpen()`

Sharpens the image. The passed integer parameter specifies the amount for the sharpening operation. The range is between 0 (no effect) and 100 (very sharp):

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->sharpen(50);

$image->save('sharpen-image.jpg');
```

### `text()`

You can add text to your image by calling `text()`. The available parameters are:

| Property           | Description                                                 |
|--------------------|-------------------------------------------------------------|
| `string $text`     | the text                                                    |
| `int               | false $offsetX`                                             | the X offset, `false` to disable                            | 
| `int               | false $offsetY`                                             | the Y offset, `false` to disable                            | 
| `int $opacity`     | the opacity of the text (optional - default `100`)          |
| `string $color`    | the color for the text (optional - default `"000000"`)      |
| `int $size`        | the size of the font for the text (optional - default `12`) |
| `string $fontfile` | the font file to be used for the text (optional)            |

The color must be a valid hex string: `#rgb`, `rgb`, `#rrggbb`, or `rrggbb`. An invalid value throws `Phalcon\Image\Exceptions\InvalidColor`.

```php
<?php

use Phalcon\Image\Adapter\Gd;

$image = new Gd('image.jpg');

$image->text(
'Phalcon Framework',
10,
10,
75,
'000033',
14,
'/app/assets/fonts/titilium.tff'
);

$image->save('text-image.jpg');
```

### `watermark()`

Adds a watermark to an image. The available parameters are:

| Property                      | Description                                         |
|-------------------------------|-----------------------------------------------------|
| `AdapterInterface $watermark` | the image to use for the watermark                  |
| `int $offsetX`                | the X offset (optional)                             |
| `int $offsetY`                | the Y offset (optional)                             | 
| `int $opacity`                | the opacity of the image (optional - default `100`) |

The watermark is read through its `render()` output, so a watermark produced by a different adapter composites correctly. Each call performs one encode/decode round trip.

The following example puts the watermark in the top left corner of the image:

```php
<?php

use Phalcon\Image\Adapter\Gd;

$watermark = new Gd('watermark.jpg');
$image     = new Gd('image.jpg');

$offsetX = 10;
$offsetY = 10;
$opacity = 70;

$image->watermark(
$watermark,
$offsetX,
$offsetY,
$opacity
);

$image->save('watermark-image.jpg');
```

You can also manipulate the watermarked image before applying it to the main image. In the following example, we resize, rotate, and sharpen the watermark and put it in the bottom right corner with a 10px margin:

```php
<?php

use Phalcon\Image\Adapter\Gd;

$watermark = new Gd('watermark.jpg');
$image     = new Gd('image.jpg');

$watermark->resize(100, 100);
$watermark->rotate(90);
$watermark->sharpen(5);

$offsetX = ($image->getWidth() - $watermark->getWidth() - 10);
$offsetY = ($image->getHeight() - $watermark->getHeight() - 10);

$opacity = 70;

$image->watermark(
$watermark,
$offsetX,
$offsetY,
$opacity
);

$image->save('watermark-image.jpg');
```

## Factory

### `newInstance`

The [Phalcon\Image\ImageFactory][image-imagefactory] offers a way to create image adapter objects. There are two adapters already preset for you:

- `gd`- [Phalcon\Image\Adapter\Gd][image-adapter-gd]
- `imagick` - [Phalcon\Image\Adapter\Imagick][image-adapter-imagick]

Calling `newInstance()` with the relevant key as well as parameters will return the relevant adapter. The factory always returns a new instance of [Phalcon\Image\Adapter\AdapterInterface][image-adapter-adapterinterface].

```php
<?php

use Phalcon\Image\ImageFactory;

$factory = new ImageFactory();

$image = $factory->newInstance('gd', 'image.jpg');
```

The available parameters for `newInstance()` are:

| Property       | Description                        |
|----------------|------------------------------------|
| `string $name` | the name of the adapter            |
| `string $file` | the file name                      |
| `int $width`   | the width of the image (optional)  |
| `int $height`  | the height of the image (optional) |

### `load`

The Image Factory also offers the `load` method, which accepts a configuration object. This object can be an array or a [Phalcon\Config\Config][config] object, with directives that are used to set up the image adapter. The object requires the `adapter` element, as well as the `file` element. `width` and `height` can also be set as options.

```php
<?php

use Phalcon\Image\ImageFactory;

$factory = new ImageFactory();
$options = [
'adapter' => 'gd',
'file'    => 'image.jpg',
'width'   => 400,
'height'  => 200,
];

$image = $factory->load($options);
```

## Custom

The [Phalcon\Image\Adapter\AdapterInterface][image-adapter-adapterinterface] interface must be implemented in order to create your own image adapters or extend the existing ones. You can then add it to the [Phalcon\Image\ImageFactory][image-imagefactory].

```php
<?php

use Phalcon\Image\Adapter\AdapterInterface;
use Phalcon\Image\Enum;

class MyImageAdapter implements AdapterInterface
{
/**
 * Manipulate the background
 */
public function background(
    string $color, 
    int $opacity = 100
);

/**
 * Blur the image
 */
public function blur(int $radius);

/**
 * Crop the image
 */
public function crop(
    int $width, 
    int $height, 
    int $offsetX = null, 
    int $offsetY = null
);

/**
 * Flip the image
 */
public function flip(int $direction);

/**
 * Add a mask to the image
 */
public function mask(AdapterInterface $watermark);

/**
 * Pixelate the image
 */
public function pixelate(int $amount);

/**
 * Add a reflection to the image
 */
public function reflection(
    int $height, 
    int $opacity = 100, 
    bool $fadeIn = false
);

/**
 * Render the image
 */
public function render(
    string $ext = null, 
    int $quality = 100
);

/**
 * Resize the image
 */
public function resize(
    int $width = null, 
    int $height = null, 
    int $master = Enum::AUTO
);

/**
 * Rotate the image
 */
public function rotate(int $degrees);

/**
 * Save the image
 */
public function save(string $file = null, int $quality = 100);

/**
 * Sharpen the image
 */
public function sharpen(int $amount);

/**
 * Add text to the image
 */
public function text(
    string $text, 
    int $offsetX = 0, 
    int $offsetY = 0, 
    int $opacity = 100, 
    string $color = "000000", 
    int $size = 12, 
    string $fontfile = null
);

/**
 * Add a watermark to the image
 */
public function watermark(
    AdapterInterface $watermark, 
    int $offsetX = 0, 
    int $offsetY = 0, 
    int $opacity = 100
);
}
```

## Exceptions

Any exceptions thrown in the Image components will be of type [Phalcon\Image\Exception][image-exception]. You can use this exception to selectively catch exceptions thrown only from this component.

```php
<?php

use Phalcon\Image\Adapter\Gd;
use Phalcon\Image\Exception;
use Phalcon\Mvc\Controller;

class IndexController extends Controller
{
public function index()
{
    try {
        $image = new Gd('image.jpg');
        $image->pixelate(10);

        $image->save('pixelated-image.jpg');
    } catch (Exception $ex) {
        echo $ex->getMessage();
    }
}
}
```

### Granular Exceptions

The component raises granular subclasses of `Phalcon\Image\Exception` so callers can catch a specific failure mode. Existing `catch (Phalcon\Image\Exception $e)` blocks continue to work unchanged.

| Class                                           | Parent                    | Thrown when                                                                |
|-------------------------------------------------|---------------------------|----------------------------------------------------------------------------|
| `Phalcon\Image\Exceptions\CompositeFailed`      | `Phalcon\Image\Exception` | A composite/overlay operation fails inside GD or Imagick.                  |
| `Phalcon\Image\Exceptions\ExtensionNotLoaded`   | `Phalcon\Image\Exception` | The required PHP extension (`gd` or `imagick`) is not loaded.              |
| `Phalcon\Image\Exceptions\ImageLoadFailed`      | `Phalcon\Image\Exception` | The image file cannot be opened or decoded.                                |
| `Phalcon\Image\Exceptions\InvalidColor`         | `Phalcon\Image\Exception` | A hex color passed to `background()` or `text()` is not valid.             |
| `Phalcon\Image\Exceptions\MissingDimensions`    | `Phalcon\Image\Exception` | An operation needs both width and height but neither has been computed.    |
| `Phalcon\Image\Exceptions\MissingHeight`        | `Phalcon\Image\Exception` | An operation needs a height value and none has been supplied.              |
| `Phalcon\Image\Exceptions\MissingWidth`         | `Phalcon\Image\Exception` | An operation needs a width value and none has been supplied.               |
| `Phalcon\Image\Exceptions\ResizeFailed`         | `Phalcon\Image\Exception` | A resize operation fails inside GD or Imagick.                             |
| `Phalcon\Image\Exceptions\ResourceTypeError`    | `Phalcon\Image\Exception` | The internal image resource is not the type expected by the adapter.       |
| `Phalcon\Image\Exceptions\TextRenderingFailed`  | `Phalcon\Image\Exception` | A `text()` operation fails inside GD or Imagick.                           |
| `Phalcon\Image\Exceptions\UnsupportedImageType` | `Phalcon\Image\Exception` | The image MIME type is not supported by the configured adapter.            |
| `Phalcon\Image\Exceptions\VersionMismatch`      | `Phalcon\Image\Exception` | The installed GD or Imagick version is older than the component's minimum. |

[config]: /5.19/config/
[gd]: https://php.net/manual/en/book.image.php
[image-adapter-abstractadapter]: /5.19/api/phalcon_image/#imageadapterabstractadapter
[image-adapter-adapterinterface]: /5.19/api/phalcon_image/#imageadapteradapterinterface
[image-adapter-gd]: /5.19/api/phalcon_image/#imageadaptergd
[image-adapter-imagick]: /5.19/api/phalcon_image/#imageadapterimagick
[image-enum]: /5.19/api/phalcon_image/#imageenum
[image-exception]: /5.19/api/phalcon_image/#imageexception
[image-imagefactory]: /5.19/api/phalcon_image/#imageimagefactory
[imagick]: https://php.net/manual/en/book.imagick.php
[imagick-liquidrescale]: https://www.php.net/manual/en/imagick.liquidrescaleimage.php

Source: https://docs.phalcon.io/5.19/image/index.mdx