Merge pull request #4 from cainmi/master

Better crop, cleaner chaining

Author: adityapatadia

README.md

@@ -1,36 +1,160 @@
 php-image-resize
 ================
 
-PHP class to re-size and scale images
+PHP class to resize and scale images.
 
-### USAGE:
-If you want to scale image:
+Setup
+-----
+
+This package is available through Packagist with the vendor and package identifier the same as this repo.
+
+If using [Composer](https://getcomposer.org/), in your `composer.json` file add:
+
+```json
+{
+    "require": {
+        "eventviva/php-image-resize": "dev-master"
+    }
+}
+```
+
+Otherwise:
 
 ```php
-$image = new ImageResize('picture.jpg');
+include '/path/to/ImageResize.php';
+```
+
+Because this class uses namespacing, when instantiating the object, you need to either use the fully qualified namespace:
+
+```php
+$image = new \Eventviva\ImageResize();
+```
+
+Or alias it:
+
+```php
+
+use \Eventviva\ImageResize;
+
+$image = new ImageResize();
+```
+
+Usage
+-----
+
+To scale an image, in this case to half it's size (scaling is percentage based):
+
+```php
+$image = new ImageResize('image.jpg');
 $image->scale(50);
-$image->save('picture2.jpg')
+$image->save('image2.jpg')
 ```
-    
-If you want to resize image:
+ 
+To resize an image according to one dimension (keeping aspect ratio):
+
 ```php
-$image = new ImageResize('picture.jpg');
+$image = new ImageResize('image.jpg');
 $image->resizeToHeight(500);
-$image->save('picture2.jpg');
-$image->resizeToWidth(200);
-$image->save('picture3.jpg');
+$image->save('image2.jpg');
+
+$image = new ImageResize('image.jpg');
+$image->resizeToWidth(300);
+$image->save('image2.jpg');
+```
+
+To to crop an image:
+
+```php
+$image = new ImageResize('image.jpg');
+$image->crop(200, 200);
+$image->save('image2.jpg');
+```
+
+This will scale the image to as close as it can to the passed dimensions, and then crop and center the rest.
+
+In the case of the example above, an image of 400px × 600px will be resized down to 200px × 300px, and then 50px will be taken off the top and bottom, leaving you with 200px × 200px.
+
+If you are happy to handle aspect ratios yourself, you can resize directly:
+
+```php
+$image = new ImageResize('image.jpg');
+$image->resize(800, 600);
+$image->save('image2.jpg');
 ```
 
-If you want to scale image: 
+This will cause your image to skew if you do not use the same width/height ratio as the source image.
+
+Displaying
+----------
+
+As seen above, you can call `$image->save('image.jpg');`
+
+To render the image directly into the browser, you can call `$image->output()`;
+
+Image Types
+-----------
+
+When saving to disk or outputting into the browser, the script assumes the same output type as input.
+
+If you would like to save/output in a different image type, you need to pass a (supported) PHP [`IMAGETYPE_`* constant](http://www.php.net/manual/en/image.constants.php):
+
+- `IMAGETYPE_GIF`
+- `IMAGETYPE_JPEG`
+- `IMAGETYPE_PNG`
+
+This allows you to save in a different type to the source:
+
 ```php
-$image = new ImageResize('picture.jpg');
-$image->scale(256,512);
-$image->save('picture4.jpg');
+$image = new ImageResize('image.jpg');
+$image->resize(800, 600);
+$image->save('image.png', IMAGETYPE_PNG);
 ```
-	
-If you want to crop image: 
+
+Quality
+-------
+
+The properties `$quality_jpg` and `$quality_png` are available for you to configure:
+
 ```php
-$image = new ImageResize('picture.jpg');
-$image->crop(512,512);
-$image->save('picture5.jpg');
+$image = new ImageResize('image.jpg');
+$image->quality_png = 100;
+$image->resize(800, 600);
+$image->save('image2.jpg');
 ```
+
+By default they are set to 75 and 0 respectively. See the manual entries for [`imagejpeg()`](http://www.php.net/manual/en/function.imagejpeg.php) and [`imagepng()`](http://www.php.net/manual/en/function.imagepng.php) for more info.
+
+You can also pass the quality directly to the `save()` and `output()` methods:
+
+```php
+$image = new ImageResize('image.jpg');
+$image->crop(200, 200);
+$image->save('image2.jpg', null, 100);
+
+$image = new ImageResize('image.jpg');
+$image->resizeToWidth(300);
+$image->output(IMAGETYPE_PNG, 4);
+```
+
+We're passing `null` for the image type in the example above to skip over it and provide the quality. In this case, the image type is assumed to be the same as the input.
+
+Chaining
+--------
+
+When performing operations, the original image is retained, so that you can chain operations without excessive destruction.
+
+This is useful for creating multiple sizes:
+
+```php
+$image = new ImageResize('image.jpg');
+$image
+    ->scale(50)
+    ->save('image2.jpg')
+
+    ->resizeToWidth(300)
+    ->save('image3.jpg')
+
+    ->crop(100, 100)
+    ->save('image4.jpg')
+;
+```