img Follow @yiiframework

Current version 1.2.2c

Img is an image manager which allows for saving, loading, deleting and versioning of images in your Yii application. Images are stored both on the hard-drive and in the database. The module utilizes the PHPThumb library to provide a wide range of image transformation options.

Img comes with an installer so it's very easy to set up and you should have it up and running in no time.

Features ¶

• Image management through one single application component
• Saving, loading and deleting of images easily
• A wide variety of image transformation options
• Active record for storing the image data
• Installer for quick and easy set up
• Extensive configuration options

Links ¶

• Discussion
• Report an issue
• Fork on Bitbucket
• PHP Thumb home

Setup ¶

Here's a step by step guide on how to set up the module:

Download the module and extract it under your modules folder. (If your application doesn't have a modules folder create it under protected.)

Configure your application according to the following example:

'import'=>array(
        .....
        'application.modules.image.components.*',
        'application.modules.image.models.Image',
),
'modules'=>array(
        .....
        'image'=>array(
                'createOnDemand'=>true, // requires apache mod_rewrite enabled
                'install'=>true, // allows you to run the installer
        ),
),
'components'=>array(
        .....
        'image'=>array(
                'class'=>'ImgManager',
                'versions'=>array(
                        'small'=>array('width'=>120,'height'=>120),
                        'medium'=>array('width'=>320,'height'=>320),
                        'large'=>array('width'=>640,'height'=>640),
                ),
        ),
),

Go to the following URL to run the installer:

index.php/image/ 
(index.php?r=image if your URL format is not set to 'path')

Save CUploadedFile objects by calling the following method:

Yii::app()->image->save($file,$model->name,'subdirectory');

Where the first argument is the CUploadedFile, the second parameter is the optional name for the image and the last parameter is the optional sub-directory where to place the image.

If you configured the image manager according to the example above you can go to the following URL to create a new version of the image you've saved:

index.php?image/default/create?id=1&version=small 
(index.php?r=image/default/create&id=1&version=small if your URL format is not set to 'path')

By default the new version of your image will be saved under /files/images/versions/small/.

Attaching the image record behavior ¶

To easily be able to save and render images you can attach the ImgRecordBehavior to your active record:

public function behaviors()
{
    return array(
        .....
        'image'=>array(
            'class'=>'image.components.ImgRecordBehavior',
            'attribute'=>'imageId', // default value
        ),
    );
}

Now if your active record has an attribute called 'imageId' and you use $model->saveImage(...) the image id will be automatically saved to your record and to render the associated image for a model you can use $model->renderImage(...). There will probably be added more features to this behavior in the future versions.

Image transformation ¶

You can load images by calling the following method:

Yii::app()->image->loadThumb($id);

Where the id is the image id. This will return an ImgThumb object on which you can apply options directly or by using the ImgOptions. Here's a few examples:

$thumb=Yii::app()->image->loadThumb($id);
$thumb->resize(640,320);
 
$options=new ImgOptions();
$options->setCropFromCenter(180);
$thumb=Yii::app()->image->loadThumb($id);
$thumb->applyOptions($options);
 
$config=array('width'=>320,'height'=>160);
$options=ImgOptions::create($config);
$thumb->applyOptions($options);
 
$thumb->save('/tmp/sample-transformed-image.jpg');

On-demand image generation ¶

Img also supports generation of image versions on-demand.

To enable on-demand generation you will need to enable the 'createOnDemand'-option for the module and the Apache mod_rewrite module on your server.

Once you've set everything up correctly image version will be created automatically when they are requested so you don't need to worry about creating all different images when you upload the image.

Change log ¶

Oct 23, 2011 ¶

• Release 1.2.2c
  • Fixed the rewrite regex for backwards compatibility

Oct 21, 2011 ¶

• Release 1.2.2b
  • Fixed the database schema

Oct 20, 2011 ¶

• Release 1.2.2
  • Added support for replacing invalid character in image filenames
  • Fixed the rewrite regex

Oct 18, 2011 ¶

• Release 1.2.1b
  • Fixed an issue with the image record validation

Oct 18, 2011 ¶

• Release 1.2.1
  • Added support for saving images in sub-directories

Oct 17, 2011 ¶

• Release 1.2.0
  • Added support for naming images
  • Improved the image behavior
  • Improved the rewrite regex

Oct 12, 2011 ¶

• Release 1.1.0
  • Added ImgRecordBehavior
  • Removed the Image parent, parents should now keep track of their image ids themselves

Aug 12, 2011 ¶

• Release 1.0.2
  • Added functionality for deleting images

Jun 23, 2011 ¶

• Release 1.0.1
  • Image file extensions will now be handled automatically
  • Removed the extension property from ImgOptions

Jun 22, 2011 ¶

• Release 1.0
  • Official release