Home

Awesome

Gregwar's Image class

Build status paypal

The Gregwar\Image class purpose is to provide a simple object-oriented images handling and caching API.

Installation

With composer :

{
    ...
    "require": {
        "gregwar/image": "2.*"
    }
}

Usage

Basic handling

Using methods chaining, you can open, transform and save a file in a single line:

<?php use Gregwar\Image\Image;

Image::open('in.png')
     ->resize(100, 100)
     ->negate()
     ->save('out.jpg');

Here are the resize methods:

resize()

scaleResize()

forceResize()

cropResize()

zoomCrop()

zoomCrop() with yPos=top

The other methods available are:

You can also create image from scratch using:

<?php
    Image::create(200, 100);

Where 200 is the width and 100 the height

Saving the image

You can save the image to an explicit file using save($file, $type = 'jpg', $quality = 80):

<?php
    // ...
    $image->save('output.jpg', 'jpg', 85);

You can also get the contents of the image using get($type = 'jpg', $quality = 80), which will return the binary contents of the image

Using cache

Each operation above is not actually applied on the opened image, but added in an operations array. This operation array, the name, type and modification time of file are hashed using sha1() and the hash is used to look up for a cache file.

Once the cache directory configured, you can call the following methods:

For instance:

<?php use Gregwar\Image\Image;

echo Image::open('test.png')
          ->sepia()
          ->jpeg();

//Outputs: cache/images/1/8/6/9/c/86e4532dbd9c073075ef08e9751fc9bc0f4.jpg

If the original file and operations do not change, the hashed value will be the same and the cache will not be generated again.

You can use this directly in an HTML document:

<?php use Gregwar\Image\Image;

// ...
<img src="<?php echo Image::open('image.jpg')->resize(150, 150)->jpeg(); ?>" />
// ...

This is powerful since if you change the original image or any of your code the cached hash will change and the file will be regenerated.

Writing image

You can also create your own image on-the-fly using drawing functions:

<?php 
    $img_src = Image::create(300, 300)
                    ->fill(0xffaaaa)    // Filling with a light red
                    ->rectangle(0xff3333, 0, 100, 300, 200, true) // Drawing a red rectangle
                      // Writing "Hello $username !" on the picture using a custom TTF font file
                    ->write('./fonts/CaviarDreams.ttf', 'Hello '.$username.'!', 150, 150, 20, 0, 'white', 'center')
                    ->jpeg();
?>
<img src="<?= $img_src  ?>" />

Using fallback image

If the image file doesn't exist, you can configure a fallback image that will be used by the class (note that this requires the cache directory to be available).

A default "error" image which is used is in images/error.jpg, you can change it with:

<?php
    $img->setFallback('/path/to/my/fallback.jpg');

Garbage Collect

To prevent the cache from growing forever, you can use the provided GarbageCollect class as below:

<?php use Gregwar\Image\GarbageCollect;

// This could be a cron called each day @3:00AM for instance
// Removes all the files from ../cache that are more than 30 days
// old. A verbose output will explain which files are deleted
GarbageCollect::dropOldFiles(__DIR__.'/../cache', 30, true);

Development

Gregwar\Image is using PHP metaprogramming paradigms that makes it easy to enhance.

Each function that handles the image is implemented in an Adapter, this is where all the specific actions take place.

The Common adapter is design to contain common abstract actions, while the specific adapters (like GD) are designed to contain actions specific to the low level layer.

You can add your own methods by adding it in the corresponding adapter.

<?php
    // In the adapter
    private function myFilter()
    {
        $this->negate();
        $this->sepia();
    }

Which could be used on the Image

<?php
    $image->myFilter();

You can also write your own adapter which could extend one of this repository and use it by calling setAdapter():

<?php
    $image->setAdapter(new MyCustomAdapter);

License

Gregwar\Image is under MIT License, please read the LICENSE file for further details. Do not hesitate to fork this repository and customize it !