README

Imagecraft is a reliable and extensible PHP image manipulation library. It can edit and compose images in multiple layers and supports watermark, resize and text. Furthermore, it keeps GIF animation, optimizes memory usage, catches memory exhausted error, and gives an user-friendly/translated feedback.

Imagecraft is intended to be an image abstraction & manipulation layer, which offers a PDO-like API. It currently supports GD extension, and will support ImageMagick in version 2.0. If you have any suggestions, comments or feedback, let me know. Thanks.

Requirement

PHP >= 5.4.0
PHP GD extension

Installation

Composer is the recommended way to install Imagecraft, simply add a dependency to your project's composer.json file:

{
    "require": {
        "coldume/imagecraft": "~1.0"
    }
}

Or, you can install from an archive file: imagecraft_1.0.4.zip

Usage

Provide the User with a Hint on What He Needs to Upload

use Imagecraft\ImageBuilder;

$options = ['engine' => 'php_gd'];
$builder = new ImageBuilder($options);
$context = $builder->about();
if (!$context->isEngineSupported()) {
    echo 'Sorry, image processing service is currently not available.'.PHP_EOL;
} else {
    $formats = $context->getSupportedImageFormatsToString();
    echo 'Make sure that you\'re using one of the following image formats: '.$formats.'.'.PHP_EOL;
    $formats = $context->getSupportedFontFormatsToString();
    echo 'We accept the following font formats: '.$formats.'.'.PHP_EOL;
}

Build an Image in Fluent Pattern

Client uploads an image from URL.
Server performs resize and watermark operations.
Server returns a message in English if an error occured, such as data size exceeds allowable limit (2MB), timeout expired (20s), file not found, etc.

use Imagecraft\ImageBuilder;

$options = ['engine' => 'php_gd', 'locale' => 'en'];
$builder = new ImageBuilder($options);
$image = $builder
    ->addBackgroundLayer()
        ->http('www.imagecraft.cc/web/images/pikachu.gif', 2048, 20)
        ->resize(400, 400, 'shrink')
        ->done()
    ->addImageLayer()
        ->filename(__DIR__.'/pikachu_what_to_do_logo_by_mnrart-d5h998b.png')
        ->move(-20, -20, 'bottom_right')
        ->done()
    ->save()
;
if ($image->isValid()) {
    file_put_contents(__DIR__.'/output.'.$image->getExtension(), $image->getContents());
} else {
    echo $image->getMessage().PHP_EOL;
}

Build an Image in Classic Pattern

Client uploads an image directly.
Server performs thumbnail and text operations.
Server returns a message in traditional Chinese if an error occured.

use Imagecraft\ImageBuilder;

$options = ['engine' => 'php_gd', 'locale' => 'zh_TW'];
$builder = new ImageBuilder($options);

$layer = $builder->addBackgroundLayer();
$layer->filename(__DIR__.'/yotsuba_koiwai.gif');
$layer->resize(150, 150, 'fill_crop');

$layer = $builder->addTextLayer();
$layer->font(__DIR__.'/minecraftia.ttf', 12, '#FFF');
$layer->label(date('F j, Y, g:i a'));
$layer->move(-10, -10, 'bottom_right');

$image = $builder->save();
if ($image->isValid()) {
    file_put_contents(__DIR__.'/output.'.$image->getExtension(), $image->getContents());
} else {
    echo $image->getMessage().PHP_EOL;
}

When Debugging is Easier than Expected

use Imagecraft\ImageBuilder;

// Build an image

if ($image->isValid()) {
    file_put_contents(__DIR__.'/output.'.$image->getExtension(), $image->getContents());
    print_r($image->getExtras());
} else {
    echo $image->getMessage().PHP_EOL;
    print_r($image->getVerboseMessage());
}

Cheat Sheet

Options

Name	Default	Available	Description
`engine`	`php_gd`	`php_gd`	image library to be used
`cache_dir`	`n/a`	`n/a`	project-specific cache directory
`debug`	`true`	`true, false`	debug mode of your project
`locale`	`en`	`en, zh_TW, ..`	error message language
`jpeg_quality`	`100`	`[0, 100]`	quality of the JPEG image
`png_compression`	`100`	`[0, 100]`	compression level of the PNG image
`memory_limit`	`-10`	`[-∞, ∞]`	maximum memory to use in MB
`gif_animation`	`true`	`true, false`	whether to maintain the GIF animation
`output_format`	`default`	`jpeg, png, ..`	output image format

Layers

Method	Compatible
`http($url,` `$dataLimit = -1,` `$timeout = -1)`	`BackgroundLayer`, `ImageLayer`
`filename($filename)`	`BackgroundLayer`, `ImageLayer`
`contents($contents)`	`BackgroundLayer`, `ImageLayer`
`resize($width, $height,` `$option = 'shrink')`	`BackgroundLayer`, `ImageLayer`
`move($x, $y,` `$gravity = 'center')`	`ImageLayer`, `TextLayer`
`font($filename,` `$size = 12, $color = '#FFF')`	`TextLayer`
`label($label)`	`TextLayer`
`angle($angle)`	`TextLayer`
`lineSpacing($lineSpacing)`	`TextLayer`
`box(array` `$paddings,` `$color = null)`	`TextLayer`

Letting your mouse hover over should cause a tooltip to appear.
Method http(), filename() or contents() is required for BackgroundLayer and ImageLayer.
Methods font() and label() are required for TextLayer.

Tips

In addition to the default English error message, Imagecraft can be switched to other languages. You can help with existing translations or to add another language. The translation files are located at:
- https://github.com/coldume/imc-stream/tree/master/src/Resources/translations
- https://github.com/coldume/imagecraft/tree/master/src/Resources/translations

Resources

Mike Flickinger (2005) "What's In A GIF".

http://giflib.sourceforge.net/whatsinagif/index.html.
David C. Kay (1994) "Graphic File Formats".

http://www.w3.org/Graphics/GIF/spec-gif89a.txt.

coldume / imagecraft

Maintainers

Details