PHPackages                             popphp/pop-image - 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. popphp/pop-image

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

popphp/pop-image
================

PHP Image library for generating, editing and effecting images. A component of the Pop PHP Framework

4.1.3(6mo ago)46.6k↓50%1BSD-3-ClausePHPPHP >=8.3.0CI passing

Since Jul 21Pushed 6mo ago1 watchersCompare

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

READMEChangelog (10)Dependencies (2)Versions (31)Used By (1)

pop-image
=========

[](#pop-image)

[![Build Status](https://github.com/popphp/pop-image/workflows/phpunit/badge.svg)](https://github.com/popphp/pop-image/actions)[![Coverage Status](https://camo.githubusercontent.com/b74366cf4753a32fd6010308857a5572921db16f972eb2bce0b722798b5b0904/687474703a2f2f63632e706f707068702e6f72672f636f7665726167652e7068703f636f6d703d706f702d696d616765)](http://cc.popphp.org/pop-image/)

[![Join the chat at https://discord.gg/TZjgT74U7E](https://camo.githubusercontent.com/acad7b0eeb78b78d08ffd2b85681ab243436388b5f86f8bcb956a69246e53739/68747470733a2f2f6d656469612e706f707068702e6f72672f696d672f646973636f72642e737667)](https://discord.gg/TZjgT74U7E)

- [Overview](#overview)
- [Install](#install)
- [Quickstart](#quickstart)
    - [Load an Image](#load-an-image)
    - [Create an Image](#create-an-image)
    - [Convert an Image](#convert-an-image)
    - [Output an Image](#output-an-image)
    - [Destroy an Image](#destroy-an-image)
- [Image Adapters](#image-adapters)
    - [GD](#gd)
    - [Imagick](#imagick)
- [Advanced Editing](#advanced-editing)
- [CAPTCHA](#captcha)

Overview
--------

[](#overview)

`pop-image` is a powerful and robust image processing component that's simple to use. It supports the GD and Imagick extensions. The API is similar to the more popular image editing application on the market, with calls to editing objects that can be extended with additional image processing functionality if needed.

`pop-image` is a component of the [Pop PHP Framework](https://www.popphp.org/).

[Top](#pop-image)

Install
-------

[](#install)

Install `pop-image` using Composer.

```
composer require popphp/pop-image

```

Or, require it in your composer.json file

```
"require": {
    "popphp/pop-image" : "^4.1.3"
}

```

[Top](#pop-image)

Quickstart
----------

[](#quickstart)

#### Resizing an image

[](#resizing-an-image)

```
use Pop\Image\Image;

$img = Image::loadGd('image.jpg');

// Resizes by using the largest dimension as the primary constraint
$img->resize(100)
    ->setQuality(50)
    ->writeToFile('image-resized.jpg');
```

```
use Pop\Image\Image;

$img = Image::loadGd('image.jpg');

// Resizes by using width as the primary constraint
$img->resizeToWidth(100)
    ->setQuality(50)
    ->writeToFile('image-resized-width.jpg');
```

```
use Pop\Image\Image;

$img = Image::loadGd('image.jpg');

// Scales the dimensions by the percentage
$img->scale(0.5)
    ->setQuality(50)
    ->writeToFile('image-scaled.jpg');
```

#### Crop the image

[](#crop-the-image)

```
use Pop\Image\Image;

$img = Image::loadGd('image.jpg');

// Crops a section of the image by width and height values
// The X and Y offsets position the crop
$img->crop(120, 80, 100, 200) // $width, $height, $xOffset, $yOffset
    ->setQuality(50)
    ->writeToFile('image-cropped.jpg');
```

#### Crop the image to a square thumbnail

[](#crop-the-image-to-a-square-thumbnail)

```
use Pop\Image\Image;

$img = Image::loadGd('image.jpg');

// The offset is automatically centered,
// unless otherwise passed as a second parameter
$img->cropThumb(100)
    ->setQuality(50)
    ->writeToFile('image-cropped-thumb.jpg');
```

[Top](#pop-image)

### Load an Image

[](#load-an-image)

There are a couple of ways to load an image into an image adapter:

#### Load from a file on disk:

[](#load-from-a-file-on-disk)

```
use Pop\Image\Image;

// Return an instance of the GD adapter
$gdImage = Image::loadGd('path/to/image.jpg');

// Returns an instance of the Imagick adapter
$imagickImage = Image::loadImagick('path/to/image.jpg');
```

#### Load from a stream of content:

[](#load-from-a-stream-of-content)

```
use Pop\Image\Image;

// Return an instance of the GD adapter
$gdImage = Image::loadGdFromString($imageContents, 'image.jpg');

// Returns an instance of the Imagick adapter
$imagickImage = Image::loadImagickFromString($imageContents, 'image.jpg');
```

[Top](#pop-image)

### Create an Image

[](#create-an-image)

There are a couple of ways to create a new image and load it into an image adapter:

#### Create an RGB-based image

[](#create-an-rgb-based-image)

```
use Pop\Image\Image;

// Return an instance of the GD adapter
$gdImage = Image::createGd(640, 480, 'image.jpg');

// Returns an instance of the Imagick adapter
$imagickImage = Image::createImagick(640, 480, 'image.jpg');
```

#### Create an index-based image

[](#create-an-index-based-image)

```
use Pop\Image\Image;

// Return an instance of the GD adapter
$gdImage = Image::createGdIndex(640, 480, 'image.gif');

// Returns an instance of the Imagick adapter
$imagickImage = Image::createImagickIndex(640, 480, 'image.gif');
```

[Top](#pop-image)

### Convert an Image

[](#convert-an-image)

You can simply convert an image to another format by calling the `convert()` method:

```
$img = Image::loadGd('image.jpg');
$img->convert('png')
    ->writeToFile('image.png');
```

**NOTE:** the GD adapter is limited to JPG, PNG and GIF formats. The Imagick adapter can work with a large number of formats, depending on your environment. The Imagick section in the `phpinfo()`result screen will display the list of formats available for Imagick in your environment.

[Top](#pop-image)

### Output an Image

[](#output-an-image)

Once you have an image adapter and have finished editing the image, you have two options to output the image.

#### Save to disk

[](#save-to-disk)

Use the `writeToFile()` method and pass it a filename and an optional image quality parameter:

```
$img->writeToFile('image-cropped-thumb.jpg', 50);
```

#### Output to HTTP

[](#output-to-http)

Use the `outputToHttp()` method to send the image content directly an HTTP client like a browser:

```
$img->outputToHttp();
```

This method has several optional parameters to assist with the delivery over HTTP:

```
outputToHttp(
    ?int $quality = null,
    ?string $to = null,
    bool $download = false,
    bool $sendHeaders = true,
    array $headers = []
): void
```

- `$quality` - set the quality of the image output
- `$to` - give it a filename for a potential download
- `$download` - boolean to set the `Content-Disposition` to inline (`false`) or attachment (`true`)
- `$sendHeaders` - boolean to send the headers or just the raw payload
- `$headers` - array of additional headers to send

[Top](#pop-image)

### Destroy an Image

[](#destroy-an-image)

Destroying an image will clear the image contents from memory to assist with memory management and prevent possibly exceeding any memory limits when working with a large number of files.

```
$img->destroy();
```

If you wish to clear the current image file from disk, you can pass a `true` boolean to the method:

```
$img->destroy(true);
```

[Top](#pop-image)

Image Adapters
--------------

[](#image-adapters)

The two image adapters available are GD and Imagick and they share a basic core API:

- `load(?string $name = null)`
- `loadFromString(string $data, ?string $name = null)`
- `create(?int $width = null, ?int $height = null, ?string $name = null)`
- `createIndex(?int $width = null, ?int $height = null, ?string $name = null)`
- `resizeToWidth(int $w)`
- `resizeToHeight(int $h)`
- `resize(int $px)`
- `scale(float $scale)`
- `crop(int $w, int $h, int $x = 0, int $y = 0)`
- `cropThumb(int $px, ?int $offset = null)`
- `rotate(int $degrees, ?Color\ColorInterface $bgColor = null, int $alpha = null)`
- `flip()`
- `flop()`

[Top](#pop-image)

### GD

[](#gd)

To work with the GD adapter, you can load it from the main image class in a few different ways:

```
use Pop\Image\Image;

// Return an instance of the GD adapter
$gdImage = Image::loadGd('path/to/image.jpg');

// Return an instance of the GD adapter
$gdImage = Image::loadGdFromString($imageContents, 'image.jpg');

// Return an instance of the GD adapter
$gdImage = Image::createGd(640, 480, 'image.jpg');

// Return an instance of the GD adapter
$gdImage = Image::createGdIndex(640, 480, 'image.jpg');
```

[Top](#pop-image)

### Imagick

[](#imagick)

To work with the Imagick adapter, you can load it from the main image class in a few different ways:

```
use Pop\Image\Image;

// Returns an instance of the Imagick adapter
$imagickImage = Image::loadImagick('path/to/image.jpg');

// Returns an instance of the Imagick adapter
$imagickImage = Image::loadImagickFromString($imageContents, 'image.jpg');

// Returns an instance of the Imagick adapter
$imagickImage = Image::createImagick(640, 480, 'image.jpg');

// Returns an instance of the Imagick adapter
$imagickImage = Image::createImagickIndex(640, 480, 'image.jpg');
```

The Imagick adapter API extends the functionality with additional Imagick-specific methods:

- `addImage(mixed $image, ?int $delay = null)`
- `hasImages()`
- `getImages()`
- `rebuildImages(\Imagick $images)`
- `setResolution(int $x, ?int $y = null)`
- `setImageColorspace(int $colorspace)`
- `setCompression(int $compression)`
- `setImageFilter(int $filter)`
- `setImageBlur(float $blur)`
- `getNumberOfImages()`
- `getCompression()`
- `getImageFilter()`
- `getImageBlur()`

[Top](#pop-image)

Advanced Editing
----------------

[](#advanced-editing)

### Using the editing objects

[](#using-the-editing-objects)

There are 6 available editing objects for advanced editing and adjusting of images:

- **Adjust** - Make image adjustments like brightness, contrast and desaturate.
- **Draw** - Draw basic shapes on the image and apply strokes and fills.
- **Effect** - Apply effects to the image, such as gradients.
- **Filter** - Apply filters to the image, such as blur, sharpen and negate.
- **Layer** - Create overlays and new layers over the image.
- **Type** - Add text over the image.

##### Examples

[](#examples)

Here are some example use cases:

```
use Pop\Image\Image;
use Pop\Image\Color\Rgb;

$img = Image::loadImagick('image.jpg');
$img->adjust->brightness(50)
    ->contrast(50);

$img->draw->setFillColor(new Rgb(255, 0, 0))
    ->rectangle(200, 200, 100, 50);

$img->effect->verticalGradient(new Rgb(255, 0, 0), new Rgb(0, 0, 255));

$img->filter->sharpen(10)
    ->swirl(30);

$img->layer->overlay('watermark.png', 200, 200);

$img->type->font('myfont.ttf')
    ->size(24)
    ->xy(50, 100)
    ->text('Hello World!');
```

[Top](#pop-image)

CAPTCHA
-------

[](#captcha)

The `pop-image` component comes with a CAPTCHA tool to create a CAPTCHA image and store the token value in session to validate the user's CAPTCHA input.

```
$captcha = new Pop\Image\Captcha('/captcha.php');
header('Content-Type: image/gif');
echo $captcha;
```

The script above will generate the following image:

[![CAPTCHA](tests/tmp/captcha.gif)](tests/tmp/captcha.gif)

And with it, the `$_SESSION` variable will store a `pop_captcha` key with a serialized value in it. When you unserialized the `$_SESSION['pop_captcha']` value, it will give you this array:

```
Array
(
    [captcha] => Reload
    [answer]  => DWB6
    [expire]  => 300
    [start]   => 1574265980
)

```

You can use the `captcha` value to display the image in an HTML page and the `answer` value to validate the user's CAPTCHA input.

[Top](#pop-image)

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance66

Regular maintenance activity

Popularity26

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity89

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 100% 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 ~150 days

Recently: every ~177 days

Total

26

Last Release

201d ago

Major Versions

2.1.1 → 3.0.02017-02-23

v2.x-dev → 3.2.22018-07-12

3.5.2 → 4.0.02023-11-19

PHP version history (8 changes)2.0.0PHP >=5.4.0

3.0.0PHP >=5.6.0

3.3.0PHP >=7.1.0

3.5.0PHP >=7.3.0

3.5.1PHP >=7.4.0

4.0.0PHP >=8.1.0

4.1.1PHP >=8.2.0

4.1.3PHP >=8.3.0

### Community

Maintainers

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

---

Top Contributors

[![nicksagona](https://avatars.githubusercontent.com/u/898670?v=4)](https://github.com/nicksagona "nicksagona (135 commits)")

---

Tags

phpimageimage resizeimage-croppoppop phpphp image libraryphp image processingimage effectsimage textdraw image

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/popphp-pop-image/health.svg)

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

###  Alternatives

[ctessier/nova-advanced-image-field

An advanced image field for Nova with cropping and resizing.

103548.4k1](/packages/ctessier-nova-advanced-image-field)[ayvazyan10/nova-imagic

Imagic is a Laravel Nova field package that allows for image manipulation capabilities, such as cropping, resizing, quality adjustment, and WebP conversion. It utilizes the powerful Intervention Image class for image manipulation.

144.3k1](/packages/ayvazyan10-nova-imagic)[lciolecki/php-image-optimizer

PHP image file optimizer (uses https://github.com/bensquire/php-image-optim)

347.4k](/packages/lciolecki-php-image-optimizer)[maxmirazh33/yii2-uploadable-cropable-image

Yii2 extension for upload and crop images

1020.8k](/packages/maxmirazh33-yii2-uploadable-cropable-image)

PHPackages © 2026

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