1. Requirements
2. Installation
3. Usage
4. Important
5. Changelog
6. Resources

This extension intend to help to "attach" file(s) to a CActiveRecord, without the help of any database, by generating file names based on the concatenation of the primary key(s). File(s) can be processed in any way you want (look at Usage).

Here is the main idea:

• A user send a file via a form linked to a model
• [optional] you can process it, and create different files from the one sended
• the file(s) is(are) saved
• when the model is deleted, files associated are deleted too

For those who knows paperclip for rails, the purpose is nearly the same, but extended as you can create formats for any file by using processors (look at the example file provided in the archive).

Requirements ¶

Yii 1.1., the php gd or imagemagick extension for ImageARBehavior.

Installation ¶

Download the archive

FileARBehavior : copy FileARBehavior in your components folder.

ImageARBehavior : copy FileARBehavior and ImageARBehavior in your components folder, then copy the image folder in your extension directory.

Usage ¶

Look at the example file provided in the archive.

Very briefly, you have to configure your behaviors() method in models. An example to generate 3 formats of image:

public function behaviors() {
  return array(
    'recipeImgBehavior' => array(
      'class' => 'ImageARBehavior',
      'attribute' => 'recipeImg', // this must exist
      'extension' => 'png, gif, jpg', // possible extensions, comma separated
      'prefix' => 'img_',
      'relativeWebRootFolder' => 'images/recipes', // this folder must exist
				
      'useImageMagick' => '/usr/bin', # I want to use imagemagick instead of GD, and
      // it is located in /usr/bin on my computer.
				
      // this will define formats for the image.
      // The format 'normal' always exist. This is the default format, by default no
      // suffix or no processing is enabled.
      'formats' => array(
        // create a thumbnail grayscale format
        'thumb' => array(
        'suffix' => '_thumb',
        'process' => array('resize' => array(60, 60), 'grayscale' => true),
      ),
      // create a large one (in fact, no resize is applied)
        'large' => array(
        'suffix' => '_large',
      ),
      // and override the default :
        'normal' => array(
        'process' => array('resize' => array(200, 200)),
      ),
    ),
				
    'defaultName' => 'default', // when no file is associated, this one is used
    // defaultName need to exist in the relativeWebRootFolder path, and prefixed by prefix,
    // and with one of the possible extensions. if multiple formats are used, a default file must exist
    // for each format. Name is constructed like this :
    //     {prefix}{name of the default file}{suffix}{one of the extension}
  )
);

Important ¶

The file (or files if you use Images with multiple formats) are generated like this :

relativWebFolder/{prefix} + join('_', primaryKeys) + {suffix} + {extension}

The suffix is only provided for images to handle multiple format.

For example, with a dish with one primary key equal to 1, you will have the following files (if you send a png image):

• files/recipes/img_1.png
• files/recipes/img_1_thumb.png
• files/recipes/img_1_large.png

Think about it to avoid name clashes if you put multiples files (from different CActiveRecord) in the same directories and be sure in this case to define different prefix for each CActiveRecord.

Changelog ¶

version 0.7

• FileARBehavior and ImageARBehavior can be placed where you want (they just need to be in the same directory)
• modification of Image extension
  • getFilePath is now called getFilesPath (there is a getFilePath method which take an argument)
  • 3 new functions (emboss, negate, grayscale)
  • The ImageMagick Driver is optimized greatly by appending arguments for convert instead of reading / saving file for each function. The temp image copy in this driver is now useless and was removed too.
• modification of FileARBehavior
  • can have formats, which can be be processed (similar to old ImageARBehavior but more generic): you can define your own processor class (look at the example file in the archive).
    • property moved from ImageARBehavior $formats -property added prcessor (set a yii import path to your own processor)
  • processing functions with no parameters (like grayscale and negate) can be set to true instead of array().
  • property added $forceExt to force saving files with a given extension.
  • property added $attributeSeparator to specify the separator used when mulitples primary keys. Default to '_'
  • getFilePath() now takes 1 optionnal argument, $format (default to 'normal')
  • getFilesPath() added, which returns an array of existing format => filePath
• modification of ImageARBehavior
  • property added $useImageMagick to use ImageMagick instead of the default GD2 library.
  • the order of the processing functions is now important ! For example, use 'process' => array('resize' => array(60, 90), 'grayscale' => true) instead of 'process' => array('grayscale' => true, 'resize' => array(60, 90)) for better performance.

version 0.5:

• allow multiple formats (not only a thumb one)
• file research and suppression now works better, by using the glob function correctly.

version 0.6:

• get file(s) path(s) in order to test if a file exists, delete when you want, etc

Resources ¶

The image extension used is modified to remove the need of the CArray file (and there is some new functions). You can use the default extension if you want by installing it instead of copying the image folder provided in my archive.

There is a forum to discuss about this extension.