Skip to content

Latest commit

 

History

History
198 lines (153 loc) · 9.19 KB

README.md

File metadata and controls

198 lines (153 loc) · 9.19 KB
Raw

Imagecraft

Build Status

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

  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;
}

Fluent Pattern Output

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;
}

Classic Pattern Output

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(Hint$url, Hint$dataLimit = -1, Hint$timeout = -1) BackgroundLayer, ImageLayer
filename($filename) BackgroundLayer, ImageLayer
contents($contents) BackgroundLayer, ImageLayer
resize($width, $height, Hint$option = 'shrink') BackgroundLayer, ImageLayer
move($x, $y, Hint$gravity = 'center') ImageLayer, TextLayer
font($filename, Hint$size = 12, $color = '#FFF') TextLayer
label($label) TextLayer
angle(Hint$angle) TextLayer
lineSpacing($lineSpacing) TextLayer
box(array Hint$paddings, Hint$color = null) TextLayer
  • Letting your mouse hover over Hint 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:

Resources