locomotivemtl/charcoal-image

PHP Image manipulation library

Charcoal Image

, _(*1)

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), _(*2)

• API Documentation

How to install

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

$ composer require locomotivemtl/charcoal-image

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., _(*4)

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)., _(*5)

The main differences between existing PHP libraries like Imagine or Intervention are:, _(*6)

• 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

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

With setData()

All effects can be added at once in a single array., _(*8)

$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., _(*9)

With magic methods

All effects can also be used as methods on the image (using __call() magic)., _(*10)

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

Also shown: using the ImageFactory constructor method:, _(*11)

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., _(*12)

Available image drivers

There are currently only 2 available drivers:, _(*13)

• 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., _(*14)

How to select a driver

There are two different ways to instantiate an Image object for a specific driver., _(*15)

Directly:, _(*16)

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

With the provided ImageFactory:, _(*17)

use \Charcoal\Image\ImageFactory;
$factory = new ImageFactory();

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

Development

To install the development environment:, _(*18)

★ composer install --prefer-source

To run the tests:, _(*19)

★ composer test

Coding Style

All Charcoal modules follow the same coding style and charcoal-image is no exception. For PHP:, _(*20)

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer
• phpDocumentor
• Arrays should be written in short notation ([] instead of array())

Coding styles are enforced with grunt phpcs (PHP Code Sniffer). The actual ruleset can be found in phpcs.xml., _(*21)

👉 To fix minor coding style problems, run grunt phpcbf (PHP Code Beautifier and Fixer). This tool uses the same ruleset as phpcs to automatically correct coding standard violations., _(*22)

The main PHP structure follow the PSR-4 standard. Autoloading is therefore provided by Composer., _(*23)

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

Continuous Integration

• Travis
• Sensio Labs
• Scrutinizer

Unit Tests

Every class, method, and function should be covered by unit tests. PHP code can be tested with PHPUnit., _(*25)

Authors

• Mathieu Ducharme mat@locomotive.ca

Changelog

0.3

Released 2016-03-11, _(*26)

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

0.2

Released 2015-09-15, _(*27)

• 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

Released 2015-08-26, _(*28)

• Initial release

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.