sfImagePoolPlugin

Introduction

A plugin that provides a global pool of images. Images can be associated with one or more Doctrine_Record objects. Images can then be resized/cropped on the fly and are cached on the filesystem (or on the edge, depending on preference). Images in the pool can be tagged, and a model's use of images restricted to a specific tag. Custom crops may be uploaded, which are then used instead of an automatically generated crop for those dimensions.

The plugin is comprised of:

sfImagePoolable Doctrine template (aka behaviour)
Admin generator module sfImagePoolAdmin for adding and removing the to the image pool, editing images (tags, name, caption, description) and uploading custom crops.
sfImagePool module for image transformations and output
sfImagePoolHelper for easy inclusion of a model's image(s) in templates
sfWidgetFormImagePoolChooser widget for selecting images and a featured image (when multiple images are being selected)
Plugin for sfMooToolsFormExtraPlugin to enable image pool images to be added into a rich text area
An improved sfThumbnail Adapter for ImageMagick which will optionally sharpen images as they're sized

Dependencies

Doctrine 1.x
Symfony 1.3/1.4
sfThumbnailPlugin
- A image manipulation library depending on which sfThumbnail adapter you choose. Defaults to ImagePoolImageMagickAdapter
MooTools Core 1.3.x
MooTools More 1.3.x:
Fx.Reveal

Optional Dependencies

sfDoctrineActAsTaggablePlugin (but only if tagging: true) in the options section of the model definition for sfImagePoolImage in schema.yml
sfMooToolsFormExtraPlugin - sfImagePoolPlugin includes an sfImaegPoolPlugin Image Chooser for MooEditable, and sfMooToolsFormExtraPlugin provides a MooEditable Symfony form widget - see Optional extensions. sfMooToolsFormExtraPlugin also provides a type-ahead input for image pool tags, if tagging is enabled (See plugin for vendors).
Rackspace Cloud files - if storing image files on a Rackspace cloud this library is required in lib/vendor/rackspace

Rackspace Cloud files: Note for SVN

If using SVN you will need to add these dependancies as svn:externals in the project's lib/vendor folder - NOTE: you need the V1.6.0 tag to work with Symfony1.4 as 1.7 onwards uses composer

rackspace  https://github.com/rackspace/php-opencloud.git/tags/V1.6.0

Rackspace Cloud files: Note for Git

The plugin's lib/vendor folder contains submodules for the Rackspace Cloud files API library, if exporting this repository then these files will also need to be exported - NOTE: you need the V1.6.0 tag to work with Symfony1.4 as 1.7 onwards uses composer

[submodule "lib/vendor/rackspace"]
  path = lib/vendor/rackspace
  url = https://github.com/rackspace/php-opencloud.git

UPGRADE TO RACKSPACE OPENCLOUD FROM CLOUDFILES

From August 2013 the php-cloudfiles API won't work. Up until then you can use the forked version: https://github.com/rackerlabs/php-cloudfiles.git/trunk and the php-cloudfiles branch of this project.

Updating your project to use php-opencloud:

Step 1: Update lib/vendor/rackspace location to https://github.com/rackspace/php-opencloud.git/tags/V1.6.0

Step 2: Remove autoload.yml entry for rackspace

Step 3: Update auth_host in config - see Customise plugin options

Step 4: Clear cache, and you're good to go

Setup

1. Enable the plugin

In ProjectConfiguration:

class ProjectConfiguration extends sfProjectConfiguration
{
  public function setup()
  {
    $this->enablePlugin('sfDoctrinePlugin', 'sfImagePoolPlugin');
  }
}
...

2. Enable modules

Typically, sfImagePoolAdmin in the backend app, and sfImagePool in all apps where you need to output images.

Every application that will handle images from the image pool should have the sfImagePool module enabled in the app's settings.yml (or globally in the project's settings.yml):

all:
 .settings:
  enabled_modules: [ sfImagePool ]

Additionally, any application that needs the image chooser widget (e.g. the Content Management System) will need to have the sfImagePoolAdmin module enabled:

all:
 .settings:
  enabled_modules: [ sfImagePool, sfImagePoolAdmin ]

It's probably a good idea to enable the ImagePoolHelper for all apps by default too:

all:
 .settings:
  standard_helpers: [ ImagePool ]

3. Add behaviour to model(s) in schema.yml

Enable tagging (optional)

Decide whether tagging should be enabled (requires sfDoctrineActAsTaggablePlugin) - add in doctrine/schema.yml

sfImagePoolImage:
  options:
    tagging:  true

NOTE: If Tagging is enabled - you'll need this in your TagTable.class.php

    /**
     * Get tags LIKE - for autocomplete
     * 
     * @param string $model
     * @param string $value
     * @return array
     */
    public function getTagsLike($model, $value)
    {
      $q = $this->createQuery('t')
               ->select('t.name')
               ->where('id IN(SELECT tag_id FROM tagging WHERE taggable_model = ?)', array($model))
               ->andWhere('t.name LIKE ?', array('%'.$value.'%'))
               ->orderBy('t.name');
       
      return $q->execute(array(), Doctrine_Core::HYDRATE_SINGLE_SCALAR);
    }

Add behaviour

MyModel:
  actAs: [sfImagePoolable]
  ...

Options

You can specify whether the model should be allowed to have multiple images, or just a single image (default) by using the multiple option. The first image selected for the model will become the 'featured' image.

MyModel:
  actAs:
    sfImagePoolable: { multiple: true }    
    ...

To restrict a model's use of images to those with the tag foo, use the tag option.

MyModel:
  actAs:
    sfImagePoolable: { tag: foo }    
    ...

To have associated images and files deleted when your object is deleted, set shared_images option to false (default is true). When true and your object is deleted, only the lookup entries are deleted, images objects and files are left untouched (i.e. remain "in the pool").

MyModel:
  actAs:
    sfImagePoolable: { shared_images: false }    
    ...

4. Add an image chooser widget to MyModelForm

To associate images with a model, the sfWidgetFormImagePoolChooser widget must be added to the model's form. The validator is required so that Symfony doesn't reject the values submitted by the additional widget.

class MyModelForm extends BaseMyModelForm
{
  public function configure()
  {
    sfImagePoolUtil::addImageChooser($this);
  }
}

Note: the form's object is passed to the widget so that it may fetch currently associated images and any sfImagePoolable options specific to that model.

5. Customise plugin options

The following options may be overridden in your app.yml files:

all:
  sf_image_pool:
    cache_lifetime:     7776000 # three months
    chooser_per_page:   24

    mimes:              [image/jpeg, image/jpg, image/png, image/pjpeg, 'image/x-png']

    # Maximum upload size to accept
    maxfilesize:        5242880

    # Folder within the web/ folder to store crops
    folder:             image-pool

    placeholders:       false # If true, use file placeholder.jpg if an image can't be found
    use_placeholdit:    false # if true, returns handy placeholder images from http://placehold.it
    placeholdit_text:   ' '   # Text to display on placehold.it image - space ' ' leaves a blank image, '' shows the size.
    use_placekitten:    false # if true placeholder images are kittens!

    inflate:            true # allow images to be scaled above their original dimensions
    jpeg_quality:       90   # JPEG quality

    require_size:       true # Add width and height attributes to image tags?

    # include controller in generated image URLs?
    use_script_name:    true
    adapter:            ImagePoolImageMagickAdapter
    # adapter:            sfGDAdapter
    adapter_options:
      # Sharpening is CPU-intensive, so you can prefix the "convert" command
      # with nice -n19 to make sure other processes get priority over the CPU
      # convert:        nice -n19 /usr/bin/convert
      # Options specific to ImagePoolImageMagickAdapter:
      # Sharpen scaled/cropped images
      sharpen:      true
      # Fix problems with thumbnail not respecting orientation with photos from certain cameras (e.g. iPhone)
      auto_orient:  true
  
    # How should we cache files?
    cache:
      lifetime:         7776000 # 4 weeks
      class:            sfImagePoolFilesystemCache
      # RACKSPACE CLOUD FILES ADAPTER:
      # class:          sfImagePoolRackspaceCloudFilesCache
      # options:
      #   username:     ~ # Your Username
      #   container:    ~ # Name for the container
      #   api_key:      ~
      #   auth_host:    LON # LON, DFW or ORD, depending on where your account is based
      # off_site_uri:   ~ # The Base URI for the container
      # off_site_ssl_uri: ~ # The Base SSL URI for the container

Rackspace Cloud files

If you want to use the Rackspace cloud to st

SfImagePoolPlugin

Install / Use

README