tiross / imagecraft

A reliable and extensible PHP image manipulation library

Imagecraft

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.6.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

1. Client uploads an image from URL.
2. Server performs resize and watermark operations.
3. 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

1. Client uploads an image directly.
2. Server performs thumbnail and text operations.
3. 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

1. 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.