# eCropPlugin plugin (for symfony 1.0.x, 1.1.x, 1.2.x) #

The `eCropPlugin` is a symfony plugin that provides mechanism for croping images

## Licence ##

This plugin is licensed under the MIT license. For the full copyright and license information, 
please view the LICENSE file that was distributed with this source code.

## Introduction ##

It supports GIF, PNG and JPG through the use of the GD library. You can
save the thumbnail in a different type from the original image. You can
save the cropped area in a different size. So for example, you could crop
a 100x100 zone and save it as a 50x50 thumbnail.

A nice way to use this plugin is to also use a javascript plugin to get
the information you need to perform the crop. Here is a 
[crop jQuery plugin](image)(http://deepliquid.com/content/Jcrop.html "image crop jQuery") 
that does that and here is a [image crop](prototype)(http://www.webresourcesdepot.com/image-crop-ui-with-prototype/)
plugin that also does that.

I commented pretty much everything in the source code, so it should be easy to look at the code and understand everything.

## Installation ##

  * Install the plugin (symfony 1.0)

	    
         symfony plugin-install http://plugins.symfony-project.com/eCropPlugin
    	

  * Install the plugin (symfony 1.1, 1.2)

	    
         symfony plugin:install eCropPlugin
    	

  * Clear you cache
	
	    
        symfony cc
    	


## Examples ##

For the purpose of the demos, we used our logo ;) So the (x,y) coordinate of the upper-left 
corner are (81, 47) and the width and height are both 97 pixels.

Original Image:  
![image][original](original)

### Sample 1: Simple Crop ###
    
    <?php
    $c = new eCrop('Leonard.png', 81, 47, 97, 97);  
    $c->crop('thumb-sample1.png');  
    

Created this 97x97 png image:  
![Crop Result][sample1](Simple)

### Sample 2: Saving in a different format ###
    
    <?php
    $c = new eCrop('Leonard.png', 81, 47, 97, 97);  
    $c->setThumbMime('image/gif');  
    $c->crop('thumb-sample2.gif');    
    

Created this 97x97 gif image:  
![Fromat Result][sample2](Different)

### Sample 3: Adjusting JPG Quality ###
    
    <?php
    $c = new eCrop('Leonard.png', 81, 47, 97, 97);  
    $c->setThumbMime('image/jpeg');  
    $c->setJpgQuality(75);  
    $c->crop('thumb-sample3.jpg');  
    

  **Note1**: The default jpg quality is 80.  

Created this 97x97 jpg image:  
![Quality Result][sample3](JPG)

### Sample 4: Saving in a different size (smaller) ###
    
    <?php
    $c = new eCrop('Leonard.png', 81, 47, 97, 97);  
    $c->setThumbSize(25, 25);  
    $c->crop('thumb-sample4.png');  
    

  **Note1**: There is also a setThumbWidth() and a setThumbHeight() method. setThumbSize() uses them internally.  
  **Note2**: There is also a setThumbSizeRelative($percentage). See phpDoc bloc inside code.  
  **Note3**: You may set the size of the thumbnail to a bigger size than the original although the thumbnail may not look so good.

Created this 25x25 png image:  
![thumbnail][sample4](Resized)

### Sample 5: Mixed options ###
    
    <?php
    $c = new eCrop('Leonard.png', 81, 47, 97, 97);  
    $c->setThumbWidth(50);  
    $c->setThumbHeight(50);  
    $c->setThumbMime('image/jpeg');  
    $c->setJpgQuality(90);  
    $c->crop('thumb-sample5.jpg');  
    

### Sample 6: Largest Square Area ###
The **cropLargestSquareArea($thumbDest, $whereToCropTall, $whereToCropWide, $free = true)** function will crop the largest possible square. 
This is useful when you want to crop an image without user input. For example, say a user upload a profile picture and you want
to create a thumbnail (like facebook). Using this function will do the trick!

Using eCrop::CROP_TOP for $whereToCropTall and eCrop::CROP_CENTER for $whereToCropWide will normally give you a thumbnail with 
face of the person on the picture.

So if a picture is vertical (taller than wide), the square will be of width x width. If the picture is horizontal, the square 
will be of height x height. The function **cropLargestSquareArea** also requires 2 parameters that determine where the crop 
will occur. The second param will be taken into account if the picture is vertical and the thrid param will be used if the 
picture is horizontal. 

Use the following constants for the $whereToCropTall param:  
  * eCrop::CROP_TOP  
  * eCrop::CROP_CENTER  
  * eCrop::CROP_BOTTOM  

Use the following constants for the $whereToCropWide param:  
  * eCrop::CROP_RIGHT  
  * eCrop::CROP_CENTER  
  * eCrop::CROP_LEFT  


    
    <?php
    $c = new eCrop('Leonard.png');  
    $c->cropLargestSquareArea('thumb-sample6a.png', eCrop::CROP_CENTER, eCrop::CROP_CENTER, false);  
    $c->setThumbSize(75, 75);  
    $c->cropLargestSquareArea('thumb-sample6b.png', eCrop::CROP_CENTER, eCrop::CROP_CENTER);  
    

  **Note1**: We introduced a new optional param to the crop* methods. The Crop methods now internally call freeAll() unless you set the 
$free param to false. So set to false if you want to save multiple crop from the same source image.

Created those 2 thumbnails:  
![square area][sample6a] ![largest square area][sample6b](largest)

## Comments & Suggestions ##
We would like to hear from people who use eCropPlugin. If you have comments or suggestions, you may contact the Lead developper.

## TODO ##
In no particular order:  
  * Add a Widget using the jQuery plugin to provide a visual way of getting (x,y) coordinate and the width/height of the zone to crop  
  * See if a form Widget would be nice too  
  * Create unit test for the whole class  
  * Refactor it so it uses the Adapter pattern to support both GD and ImageMagik like sfThumbnailPlugin does  
  * Create a demo using the jQuery plugin  

## Changelog ##

See subversion changeset for changelog

[original]: http://www.leonarddg.com/symfony/plugins/eCropPlugin/images/Leonard.png "Original Image"
[sample1]: http://www.leonarddg.com/symfony/plugins/eCropPlugin/images/thumb-sample1.png "Simple Crop"
[sample2]: http://www.leonarddg.com/symfony/plugins/eCropPlugin/images/thumb-sample2.gif "Saving in a different format"
[sample3]: http://www.leonarddg.com/symfony/plugins/eCropPlugin/images/thumb-sample3.jpg "Adjusting JPG Quality"
[sample4]: http://www.leonarddg.com/symfony/plugins/eCropPlugin/images/thumb-sample4.png "Saving in a different size"
[sample5]: http://www.leonarddg.com/symfony/plugins/eCropPlugin/images/thumb-sample5.jpg "Using mixed options"
[sample6a]: http://www.leonarddg.com/symfony/plugins/eCropPlugin/images/thumb-sample6a.png "Largest Square Area"
[sample6b]: http://www.leonarddg.com/symfony/plugins/eCropPlugin/images/thumb-sample6b.png "Largest Square Area"