locomotivemtl / charcoal-image
PHP Image manipulation library
Installs: 20 177
Dependents: 1
Suggesters: 0
Security: 0
Stars: 2
Watchers: 13
Forks: 0
Open Issues: 1
Requires
- php: >=5.6.0 || >=7.0
- locomotivemtl/charcoal-factory: ^0.4
Requires (Dev)
- phpunit/phpunit: ^5.7 || ^6.5
- satooshi/php-coveralls: ^2.0
- squizlabs/php_codesniffer: ^3.0
Suggests
- ext-SimpleXML: To parse sprite (SVG) property.
- ext-imagick: To use the imagick driver.
This package is auto-updated.
Last update: 2024-10-30 01:48:19 UTC
README
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)
How to install
The preferred (and only supported) way of installing charcoal-image is with composer:
$ composer require locomotivemtl/charcoal-image
Dependencies
PHP 5.6+
locomotivemtl/charcoal-factory
ext-imagick
(optional but recommended) ORImageMagick 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 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)
orblur($radius, $sigma)
? - With charcoal image it's constant:
blur([ 'radius' => $radius, 'sigma' => $sigma ]);
- Is it
- 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.
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
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
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.
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.
- The imagick driver use the
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
andidentify
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
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
To install the development environment:
★ composer install --prefer-source
To run the tests:
★ composer test
Coding Style
All Charcoal modules follow the same coding style and charcoal-image
is no exception. For PHP:
- PSR-1
- PSR-2
- PSR-4, autoloading is therefore provided by Composer
- phpDocumentor
- Arrays should be written in short notation (
[]
instead ofarray()
)
Coding styles are enforced with grunt phpcs
(PHP Code Sniffer). The actual ruleset can be found in phpcs.xml
.
👉 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.
The main PHP structure follow the PSR-4 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
Unit Tests
Every class, method, and function should be covered by unit tests. PHP code can be tested with PHPUnit.
Authors
- Mathieu Ducharme mat@locomotive.ca
Changelog
0.3
Released 2016-03-11
- Break BC in every way.
- Convert to camelCase / Full PSR-1 / PSR-2 support.
0.2
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
Released 2015-08-26
- 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.