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

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

locomotivemtl/charcoal-image
============================

PHP Image manipulation library

v0.4.3.4(2y ago)220.5k[1 issues](https://github.com/locomotivemtl/charcoal-image/issues)1MITPHPPHP >=5.6.0 || >=7.0CI failing

Since Aug 27Pushed 2y ago11 watchersCompare

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

READMEChangelog (10)Dependencies (4)Versions (15)Used By (1)

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

[](#charcoal-image)

[![Build Status](https://camo.githubusercontent.com/e2170b62d79157f606fbf3d2fa63b8044e3a637be961a7ad7c64e21d7737a439/68747470733a2f2f7472617669732d63692e6f72672f6c6f636f6d6f746976656d746c2f63686172636f616c2d696d6167652e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/locomotivemtl/charcoal-image)

Charcoal Image is a PHP image manipulation and processing library, providing a consistent API across different Image drivers. Currently supported drivers are `Imagick` (the PHP extension) and `Imagemagick` (using shell commands)

- [API Documentation](docs/api.md)

How to install
==============

[](#how-to-install)

The preferred (and only supported) way of installing charcoal-image is with **composer**:

```
$ composer require locomotivemtl/charcoal-image
```

Dependencies
------------

[](#dependencies)

- `PHP 5.6+`
- `locomotivemtl/charcoal-factory`
- `ext-imagick` (optional but *recommended*) **OR**
- `ImageMagick binaries`

> 👉 Although this module was developped for `Charcoal`, there is absolutely no dependencies on any Charcoal modules and can therefore be used in any PHP project.

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. charcoal-image can be used
- No external dependencies, except the tiny `charcoal-factory`.

Usage
=====

[](#usage)

Typically, *charcoal-image* 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');
```

Development
===========

[](#development)

To install the development environment:

```
★ composer install --prefer-source
```

To run the tests:

```
★ composer test
```

Coding Style
------------

[](#coding-style)

All Charcoal modules follow the same coding style and `charcoal-image` is no exception. For PHP:

- [*PSR-1*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md)
- [*PSR-2*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
- [*PSR-4*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md), autoloading is therefore provided by *Composer*
- [*phpDocumentor*](http://phpdoc.org/)
- Arrays should be written in short notation (`[]` instead of `array()`)

Coding styles are enforced with `grunt phpcs` ([*PHP Code Sniffer*](https://github.com/squizlabs/PHP_CodeSniffer)). The actual ruleset can be found in `phpcs.xml`.

> 👉 To fix minor coding style problems, run `grunt phpcbf` ([*PHP Code Beautifier and Fixer*](https://github.com/squizlabs/PHP_CodeSniffer)). This tool uses the same ruleset as *phpcs* to automatically correct coding standard violations.

The main PHP structure follow the [*PSR-4*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md) standard. Autoloading is therefore provided by *Composer*.

To ensure a clean code base, pre-commit git hooks should be installed on all development environments.

Continuous Integration
----------------------

[](#continuous-integration)

- [Travis](https://travis-ci.org/locomotivemtl/charcoal-image)
- [Sensio Labs](https://insight.sensiolabs.com/projects/87c9621d-3b2e-4e71-a42f-e69ebca4672e)
- [Scrutinizer](https://scrutinizer-ci.com/)

Unit Tests
----------

[](#unit-tests)

Every class, method, and function should be covered by unit tests. PHP code can be tested with [*PHPUnit*](https://phpunit.de/).

Authors
-------

[](#authors)

- Mathieu Ducharme

Changelog
---------

[](#changelog)

### 0.3

[](#03)

*Released 2016-03-11*

- Break BC in every way.
- Convert to camelCase / Full PSR-1 / PSR-2 support.

### 0.2

[](#02)

*Released 2015-09-15*

- Add a new "auto-orientation" effect (imagick + imagemagick)
- Add the watermark effect to imagemagick (imagemagick)
- Fixed the "unsharp mask" mode for sharpen effect (imagick)
- Fixed the gravity for the watermark effect (imagick)
- Accept *ImageInterface* objects as watermark (global)
- Add a dependency on `locomotivemtl/charcoal-factory` and fix factories accordingly. (global)

### 0.1

[](#01)

*Released 2015-08-26*

- Initial release

TODOs
-----

[](#todos)

- Write a version for PHP's `gd` driver.
- Custom Exceptions.
- Change effect signature to be callable (invokable) instead of using the process() method.
- Skip unit tests instead of failing if a driver is not available.

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance10

Infrequent updates — may be unmaintained

Popularity25

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 67.9% 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 ~279 days

Recently: every ~541 days

Total

12

Last Release

833d ago

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

v0.3PHP >=5.5.0

v0.4.3.3PHP >=5.6.0 || >=7.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)

---

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 (21 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

phpimageImageMagickgdimagickcharcoallocomotive

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

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

```
[![Health](https://phpackages.com/badges/locomotivemtl-charcoal-image/health.svg)](https://phpackages.com/packages/locomotivemtl-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)