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

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

charcoal/image
==============

PHP Image manipulation library

v5.0.0(2y ago)0951MITPHPPHP ^7.4 || ^8.0

Since Aug 27Pushed 2y ago2 watchersCompare

[ Source](https://github.com/charcoalphp/image)[ Packagist](https://packagist.org/packages/charcoal/image)[ RSS](/packages/charcoal-image/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (4)Versions (38)Used By (1)

Charcoal Image
==============

[](#charcoal-image)

The Image package provides a consistent API for image manipulation and processing with integrations for GD (coming soon) and ImageMagick (via the PHP extension or via shell commands).

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

[](#installation)

```
composer require charcoal/image
```

Overview
--------

[](#overview)

### Why another PHP image libary?

[](#why-another-php-image-libary)

*Why not?*. Charcoal Image has been developped and used in in-house projects for almost 10 years. It has recently been rewritten to a more modern PHP style and released under an open-source license (MIT).

The main differences between existing PHP libraries like *Imagine* or *Intervention* are:

- Effect parameters are sent as an array.
    - Is it `blur($sigma, $radius)` or `blur($radius, $sigma)`?
    - With charcoal image it's constant: `blur([ 'radius' => $radius, 'sigma' => $sigma ]);`
- It supports *ImageMagick* binaries
    - It seems to be a pretty common setup where Imagemagick is installed on a server, but the *Imagick* PHP library is not.
- No external dependencies, except the tiny [charcoal/factory](https://github.com/charcoalphp/factory).

Usage
-----

[](#usage)

Typically, the Image package is used to load an image, perform operations (called *effects* such as blur, resize, watermark, etc.) and write the modified image.

### With `setData()`

[](#with-setdata)

All effects can be added at once in a single array.

```
$img = new Charcoal\Image\Imagick\ImagickImage();

$img->setData([
    'source'  => 'example.png',
    'target'  => 'example-modified.png',
    'effects' => [
        [
            'type'  => 'resize',
            'width' => 600,
        ],
        [
            'type'  => 'blur',
            'mode'  => 'gaussian',
            'sigma' => 5,
        ],
    ],
]);
$img->process();
$img->save();
```

> `setData()` is perfect for scenario where the effects are from a JSON configuration structure, for example.

### With magic methods

[](#with-magic-methods)

All effects can also be used as methods on the image (using `__call()` magic).

```
use Charcoal\Image\Imagick\ImagickImage as Image;

$img = new Image();
$img->open('example.png');
$img->resize([
    'width' => 600
]);
$img->blur([
    'mode'  => 'gaussian',
    'sigma' => 5
]);
$img->save();
```

#### Chainable version

[](#chainable-version)

Also shown: using the `ImageFactory` constructor method:

```
use Charcoal\Image\ImageFactory;

$factory = new ImageFactory();
$img = $factory->create('imagemagick');
$img->open('example.png')
    ->resize([
        'mode'   => 'best_fit',
        'width'  => 350,
        'height' => 350,
    ])
    ->rotate([
        'angle' => 90,
    ])
    ->modulate([
        'luminance' => 50,
    ])
    ->save('modified-target.png');
```

Available effects and operations are documented in the [API Documentation](docs/api.md).

### Available image drivers

[](#available-image-drivers)

There are currently only 2 available drivers:

- `imagick`
    - The imagick driver use the `Imagick` PHP extension, which is build on top of imagemagick.
- `imagemagick`
    - The imagemagick driver uses the imagmagick binaries directly, running the operations in a separate shell process instead of directely within PHP.
    - The commands `convert`, `mogrify` and `identify` should be installed on the system and reachable from the PHP process.

> 👉 Comming soon, the `gd` driver to use PHP builtin's image capacity.

### How to select a driver

[](#how-to-select-a-driver)

There are two different ways to instantiate an *Image* object for a specific driver.

Directly:

```
$img = new Charcoal\Image\Imagick\ImagickImage();
// or
$img = new Charcoal\Image\Imagemagick\ImagemagickImage();
```

With the provided `ImageFactory`:

```
use Charcoal\Image\ImageFactory;

$factory = new ImageFactory();

$img = $factory->create('imagick');
// or
$img = $factory->create('imagemagick');
```

Resources
---------

[](#resources)

- [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)
- [Report issues](https://github.com/charcoalphp/charcoal/issues) and [send pull requests](https://github.com/charcoalphp/charcoal/pulls)in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity80

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 60.7% 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 ~92 days

Recently: every ~15 days

Total

35

Last Release

794d ago

Major Versions

v0.4.3.3 → v2.1.22022-06-21

v2.2.3 → v3.1.02022-08-08

v3.1.8 → v4.0.02022-09-21

v4.1.0 → v5.0.02024-03-13

PHP version history (4 changes)v0.1PHP >=5.4.0

v0.3PHP >=5.5.0

v0.4.3.3PHP >=5.6.0 || >=7.0

v2.1.2PHP ^7.4 || ^8.0

### Community

Maintainers

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

![](https://www.gravatar.com/avatar/0a4f39523b4b2837562ba0848a0327b8d340118d1ba87cb0f5d59b1d5cb6beba?d=identicon)[mcaskill](/maintainers/mcaskill)

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

![](https://www.gravatar.com/avatar/4229f19eecd12c2b651b6502dcc5adfba48c5770db3d2dbea55fc92c7a246b2b?d=identicon)[BeneRoch](/maintainers/BeneRoch)

---

Top Contributors

[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (74 commits)")[![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (18 commits)")[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (16 commits)")[![BeneRoch](https://avatars.githubusercontent.com/u/3017380?v=4)](https://github.com/BeneRoch "BeneRoch (6 commits)")[![JoelAlphonso](https://avatars.githubusercontent.com/u/10762266?v=4)](https://github.com/JoelAlphonso "JoelAlphonso (4 commits)")[![dominiclord](https://avatars.githubusercontent.com/u/1775204?v=4)](https://github.com/dominiclord "dominiclord (3 commits)")[![veve40](https://avatars.githubusercontent.com/u/7537381?v=4)](https://github.com/veve40 "veve40 (1 commits)")

---

Tags

image-processingimagemagickimagickphpphpread-only-repositoryphpimageImageMagickgdimagickcharcoallocomotive

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

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

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

###  Alternatives

[league/glide

Wonderfully easy on-demand image manipulation library with an HTTP based API.

2.6k51.2M116](/packages/league-glide)[orbitale/imagemagick-php

A system that allows creating commands to send to the exec() function to use ImageMagick's powerful features.

43385.7k1](/packages/orbitale-imagemagick-php)[admad/cakephp-glide

CakePHP plugin for using Glide image manipulation library.

34160.7k1](/packages/admad-cakephp-glide)[phpixie/image

PHPixie imageprocessing library

4756.5k6](/packages/phpixie-image)[thapp/jitimage

Just in time image manipulation.

997.5k1](/packages/thapp-jitimage)

PHPackages © 2026

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