mirror/intervention_image
1
0
Fork 0
mirror of https://github.com/Intervention/image.git synced 2025-08-18 03:31:19 +02:00
Code Issues Releases Wiki Activity

documentation improvements

Browse Source
This commit is contained in:
Oliver Vogel
2013-03-21 14:28:23 +01:00
parent 827c542017
commit 774a0dfb06
4 changed files with 51 additions and 302 deletions
Download Patch File Download Diff File Expand all files Collapse all files

263
README.md
View File

@@ -1,266 +1,15 @@
# Intervention Image Class # Intervention Image Class
Intervention Image Class is an image handling and manipulation wrapper library using [PHP GD library](http://www.php.net/manual/book.image.php). The class is written to make PHP image manipulating more easier and expressive. Intervention Image is a PHP Image handling and manipulation class with support for Laravel 4 integration.
The library requires at least **PHP version 5.3** and comes with [Laravel 4](https://github.com/laravel/framework/) Facades and Service Providers to simplify the optional framework integration. ## Documentation
## Installation Refer to the following guide on how to use Intervention Image Class.
You can install this Image class quickly and easily with Composer. [Intervention Image Class Documentation](http://intervention.olivervogel.net/image/)
Require the package via Composer in your `composer.json`.
"intervention/image": "dev-master"
Run Composer to install or update the new requirement.
$ composer update
Now you are able to require the `vendor/autoload.php` file to PSR-0 autoload the library.
### Laravel 4 Integration
The Image class also has optional Laravel 4 support. The integration into the framework is done in seconds.
Open your Laravel config file `config/app.php` and add the following lines.
In the `$providers` array add the service providers for this package.
'providers' => array(
[...]
'Intervention\Image\ImageServiceProvider'
),
Add the facade of this package to the `$aliases` array.
'aliases' => array(
[...]
'Image' => 'Intervention\Image\Facades\Image'
),
## Usage
* Image::__construct - Create new instance of Image class
* Image::make - Open a new image resource from image file
* Image::canvas - Create a new empty image resource
* Image::raw - Create a new image resource with image data from string
* Image::open - Open a new image resource from image file
* Image::resize - Resize current image based on given width and/or height
* Image::crop - Crop the current image
* Image::grab - Cut out a detail of the image in given ratio and resize to output size
* Image::resizeCanvas - Resize image boundaries
* Image::opacity - Set opacity of current image
* Image::mask - Apply given image as alpha mask on current image
* Image::insert - Insert another image on top of the current image
* Image::brightness - Changes brightness of current image (-100 = min brightness, 0 = no change, +100 = max brightness)
* Image::contrast - Changes contrast of current image (-100 = min contrast, 0 = no change, +100 = max contrast)
* Image::pixelate - Pixelate current image
* Image::greyscale - Turn current image into a greyscale version
* Image::invert - Invert colors of current image
* Image::rotate - Rotate image by a given value
* Image::flip - Mirror image horizontally or vertically
* Image::text - Write text in current image
* Image::fill - Fill image with given color or image at position x,y
* Image::rectangle - Draw rectangle in current image starting at point 1 and ending at point 2
* Image::line - Draw a line in current image starting at point 1 and ending at point 2
* Image::ellipse - Draw an ellipse centered at given coordinates
* Image::circle - Draw a circle centered at given coordinates
* Image::pixel - Set single pixel with given color at position x,y
* Image::pickColor - Picks and formats color at position in current image
* Image::reset - Reset to original image resource
* Image::save - Save image in filesystem
* Image::__toString - Returns image data depending on current format
### Code examples (Laravel)
#### Resize images
```php
// create Image from file
$img = Image::make('public/foo.jpg');
// resize image to fixed size
$img->resize(300, 200);
// resize only the width of the image
$img->resize(300, null);
// resize only the height of the image
$img->resize(null, 200);
// resize the image to a width of 300 and constrain aspect ratio (auto height)
$img->resize(300, null, true);
// resize the image to a height of 200 and constrain aspect ratio (auto width)
$img->resize(null, 200, true);
// prevent possible upsizing with optional fourth parameter
$img->resize(null, 400, true, false);
// Reset image resource to original
$img->reset();
// save image in desired format and quality
$img->save('public/bar.jpg', 60);
```
#### Resize canvas
```php
// create Image from file
$img = Image::make('public/foo.jpg');
// resize image canvas
$img->resizeCanvas(300, 200);
// resize only the width of the canvas
$img->resizeCanvas(300, null);
// resize only the height of the canvas
$img->resizeCanvas(null, 200);
// resize the canvas by cutting out bottom right position
$img->resizeCanvas(300, 200, 'bottom-right');
// resize the canvas relative by setting the third parameter to true
$img->resizeCanvas(10, -10, 'center', true);
// set a background-color for the emerging area
$img->resizeCanvas(1280, 720, 'center', false, 'ff00ff');
```
#### Crop image
```php
// create Image from file
$img = Image::make('public/foo.jpg');
// crop 300x200 pixel cutout at position x:200, y:100
$img->crop(300, 200, 200, 100);
// crop 300x200 pixel cutout centered on current image
$img->crop(300, 200);
// save image
$img->save();
```
#### Smart resizing
```php
// use grab method to format images in a smart way combining cropping and resizing
$img = Image::make('public/foo.jpg');
// crop the best fitting 1:1 ratio (200x200) and resize to 200x200 pixel
$img->grab(200);
// crop the best fitting 5:3 (600x360) ratio and resize to 600x360 pixel
$img->grab(600, 360);
// save image
$img->save('public/bar.jpg');
```
#### Create empty images and add content
```php
// create an empty Image resource (background color transparent)
$img = Image::canvas(640, 480);
// insert another image on top of current resource
$img->insert('public/bar.png');
// write some text in image
$img->text('Hello World', 10, 10);
// save image in desired format
$img->save('public/foo.jpg');
```
#### Image filters
```php
// create Image from file
$img = Image::make('public/foo.jpg');
// turn image into greyscale version
$img->greyscale();
// modify brightness level
$img->brightness(80);
// modify contrast level
$img->contrast(-45);
// pixelate image with blocksize of 25x25 pixel
$img->pixelate(25);
```
#### Other examples
```php
// create empty canvas
$img = Image::canvas(800, 600);
// fill image with color
$img->fill('cccccc');
// fill image with tiled image
$img->fill(Image::make('tile.png'));
// draw a filled rectangle
$img->rectangle('006729', 100, 100, 200, 200, true);
// draw a outline circle
$img->circle('ae051f', 400, 300, 100, false);
// draw a red line from point 10,10 to point 300,300 pixel
$img->line('ae051f', 10, 10, 300, 300);
// Apply image as alpha mask on image
$img->mask('public/mask.png', true);
// rotate image 90° clockwise
$img->rotate(90);
// set 75% opacity
$img->opacity(75);
// flip image horizontally
$img->flip('h');
// flip image vertically
$img->flip('v');
```
#### Method chaining
```php
// it is possible to chain all methods
$img1 = Image::canvas(800, 600);
$img2 = Image::make('public/img2.png');
$img1->resize(300, 200)->insert($img2)->save('public/bar.jpg');
```
## Image Caching
The optional package [Intervention Image Cache](https://github.com/Intervention/imagecache/) extends the package to be capable of image caching. `Image::cache` will automatically detect if a cached file for the particular operations exists.
```php
// run the operations on the image or read a file
// for the particular operations from cache
$img = Image::cache(function($image) {
return $image->make('public/foo.jpg')->resize(300, 200)->greyscale();
});
```
Read more about [Intervention Image Cache](https://github.com/Intervention/imagecache/).
## License ## License
Intervention Image Class is licensed under the [MIT License](http://opensource.org/licenses/MIT). Intervention Image Class is licensed under the [MIT License](http://opensource.org/licenses/MIT).
Copyright 2013 [Oliver Vogel](http://olivervogel.net/)

2
composer.json
View File

@@ -1,7 +1,7 @@
{ {
"name": "intervention/image", "name": "intervention/image",
"description": "Image handling and manipulation library with support for Laravel 4 integration", "description": "Image handling and manipulation library with support for Laravel 4 integration",
"homepage": "https://github.com/Intervention/image", "homepage": "http://intervention.olivervogel.net/image/",
"keywords": ["image", "gd", "laravel"], "keywords": ["image", "gd", "laravel"],
"license": "MIT", "license": "MIT",
"authors": [ "authors": [

84
src/Intervention/Image/Image.php
View File

@@ -10,77 +10,77 @@ class Image
{ {
/** /**
* The image resource identifier of current image * The image resource identifier of current image
* *
* @var resource * @var resource
*/ */
public $resource; public $resource;
/** /**
* Type of current image * Type of current image
* *
* @var string * @var string
*/ */
public $type; public $type;
/** /**
* Width of current image * Width of current image
* *
* @var integer * @var integer
*/ */
public $width; public $width;
/** /**
* Height of current image * Height of current image
* *
* @var integer * @var integer
*/ */
public $height; public $height;
/** /**
* Directory path of current image * Directory path of current image
* *
* @var string * @var string
*/ */
public $dirname; public $dirname;
/** /**
* Trailing name component of current image filename * Trailing name component of current image filename
* *
* @var string * @var string
*/ */
public $basename; public $basename;
/** /**
* File extension of current image filename * File extension of current image filename
* *
* @var string * @var string
*/ */
public $extension; public $extension;
/** /**
* Combined filename (basename and extension) * Combined filename (basename and extension)
* *
* @var string * @var string
*/ */
public $filename; public $filename;
/** /**
* Instance of Illuminate\Filesystem\Filesystem * Instance of Illuminate\Filesystem\Filesystem
* *
* @var Filesystem * @var Filesystem
*/ */
protected $filesystem; protected $filesystem;
/** /**
* Attributes of the original created image * Attributes of the original created image
* *
* @var Array * @var Array
*/ */
protected $original; protected $original;
/** /**
* Identifier for cached images * Identifier for cached images
* *
* @var boolean * @var boolean
*/ */
public $cached = false; public $cached = false;
@@ -97,8 +97,8 @@ class Image
{ {
// create filesystem // create filesystem
$this->filesystem = new Filesystem; $this->filesystem = new Filesystem;
// set image properties // set image properties
if ( ! is_null($path)) { if ( ! is_null($path)) {
$this->setPropertiesFromPath($path); $this->setPropertiesFromPath($path);
@@ -177,7 +177,7 @@ class Image
/** /**
* Set properties for image resource from image file * Set properties for image resource from image file
* *
* @param string $path * @param string $path
* @return void * @return void
*/ */
@@ -235,7 +235,7 @@ class Image
/** /**
* Set properties for empty image resource * Set properties for empty image resource
* *
* @param int $width * @param int $width
* @param int $height * @param int $height
* @param mixed $bgcolor * @param mixed $bgcolor
@@ -259,7 +259,7 @@ class Image
} else { } else {
$bgcolor = $this->parseColor($bgcolor); $bgcolor = $this->parseColor($bgcolor);
} }
imagefill($this->resource, 0, 0, $bgcolor); imagefill($this->resource, 0, 0, $bgcolor);
} }
@@ -398,11 +398,11 @@ class Image
throw new Exception('width or height needs to be defined'); throw new Exception('width or height needs to be defined');
} elseif (is_null($width)) { // If only the width hasn't been set, keep the current width. } elseif (is_null($width)) { // If only the width hasn't been set, keep the current width.
$width = $this->width; $width = $this->width;
} elseif (is_null($height)) { // If only the height hasn't been set, keep the current height. } elseif (is_null($height)) { // If only the height hasn't been set, keep the current height.
$height = $this->height; $height = $this->height;
} }
@@ -426,7 +426,7 @@ class Image
/** /**
* Resize image canvas * Resize image canvas
* *
* @param int $width * @param int $width
* @param int $height * @param int $height
* @param string $anchor * @param string $anchor
@@ -444,7 +444,7 @@ class Image
if ($relative) { if ($relative) {
$width = $this->width + $width; $width = $this->width + $width;
$height = $this->height + $height; $height = $this->height + $height;
} }
// check for negative width // check for negative width
if ($width <= 0) { if ($width <= 0) {
@@ -520,7 +520,7 @@ class Image
$src_x = ($width < $this->width) ? intval(($this->width - $width) / 2) : 0; $src_x = ($width < $this->width) ? intval(($this->width - $width) / 2) : 0;
$src_y = ($height < $this->height) ? intval($this->height - $height) : 0; $src_y = ($height < $this->height) ? intval($this->height - $height) : 0;
break; break;
case 'bottom-right': case 'bottom-right':
$src_x = ($width < $this->width) ? intval($this->width - $width) : 0; $src_x = ($width < $this->width) ? intval($this->width - $width) : 0;
$src_y = ($height < $this->height) ? intval($this->height - $height) : 0; $src_y = ($height < $this->height) ? intval($this->height - $height) : 0;
@@ -588,7 +588,7 @@ class Image
* *
* @param integer $width * @param integer $width
* @param integer $height * @param integer $height
* *
* @return Image * @return Image
*/ */
public function grab($width = null, $height = null) public function grab($width = null, $height = null)
@@ -665,7 +665,7 @@ class Image
$y = $height - 1; $y = $height - 1;
$height = $height * (-1); $height = $height * (-1);
break; break;
default: default:
$x = $width - 1; $x = $width - 1;
$width = $width * (-1); $width = $width * (-1);
@@ -693,21 +693,21 @@ class Image
/** /**
* Set opacity of current image * Set opacity of current image
* *
* @param integer $value * @param integer $transparency
* @return Image * @return Image
*/ */
public function opacity($value) public function opacity($transparency)
{ {
if ($value >= 0 && $value <= 100) { if ($transparency >= 0 && $transparency <= 100) {
$value = intval($value) / 100; $transparency = intval($transparency) / 100;
} else { } else {
throw new Exception('Opacity must be between 0 and 100'); throw new Exception('Opacity must be between 0 and 100');
} }
// create alpha mask // create alpha mask
$alpha = new self(null, $this->width, $this->height); $alpha = new self(null, $this->width, $this->height);
$alpha->fill(sprintf('rgba(0, 0, 0, %.1f)', $value)); $alpha->fill(sprintf('rgba(0, 0, 0, %.1f)', $transparency));
// apply alpha mask // apply alpha mask
$this->mask($alpha, true); $this->mask($alpha, true);
@@ -741,7 +741,7 @@ class Image
$color = $this->pickColor($x, $y, 'array'); $color = $this->pickColor($x, $y, 'array');
$alpha = $mask->pickColor($x, $y, 'array'); $alpha = $mask->pickColor($x, $y, 'array');
if ($mask_with_alpha) { if ($mask_with_alpha) {
$alpha = $alpha['alpha']; // use alpha channel as mask $alpha = $alpha['alpha']; // use alpha channel as mask
} else { } else {
@@ -774,10 +774,10 @@ class Image
* @param int $ignore_transparent * @param int $ignore_transparent
* @return Image * @return Image
*/ */
public function rotate($angle = 0, $color = '#000000', $ignore_transparent = 0) public function rotate($angle = 0, $bgcolor = '#000000', $ignore_transparent = 0)
{ {
// rotate image // rotate image
$this->resource = imagerotate($this->resource, $angle, $this->parseColor($color), $ignore_transparent); $this->resource = imagerotate($this->resource, $angle, $this->parseColor($bgcolor), $ignore_transparent);
// re-read width/height // re-read width/height
$this->width = imagesx($this->resource); $this->width = imagesx($this->resource);
@@ -809,7 +809,7 @@ class Image
$color = IMG_COLOR_TILED; $color = IMG_COLOR_TILED;
} else { } else {
// fill with color // fill with color
$color = $this->parseColor($color); $color = $this->parseColor($color);
} }
@@ -874,16 +874,16 @@ class Image
* Draw an ellipse centered at given coordinates. * Draw an ellipse centered at given coordinates.
* *
* @param string $color * @param string $color
* @param integer $x * @param integer $pos_x
* @param integer $y * @param integer $pos_y
* @param integer $width * @param integer $width
* @param integer $height * @param integer $height
* @return Image * @return Image
*/ */
public function ellipse($color, $x = 0, $y = 0, $width = 10, $height = 10, $filled = true) public function ellipse($color, $pos_x = 0, $pos_y = 0, $width = 10, $height = 10, $filled = true)
{ {
$callback = $filled ? 'imagefilledellipse' : 'imageellipse'; $callback = $filled ? 'imagefilledellipse' : 'imageellipse';
call_user_func($callback, $this->resource, $x, $y, $width, $height, $this->parseColor($color)); call_user_func($callback, $this->resource, $pos_x, $pos_y, $width, $height, $this->parseColor($color));
return $this; return $this;
} }
@@ -1010,7 +1010,7 @@ class Image
/** /**
* Invert colors of current image * Invert colors of current image
* *
* @return Image * @return Image
*/ */
public function invert() public function invert()
@@ -1028,7 +1028,7 @@ class Image
public function reset() public function reset()
{ {
if (is_null($this->dirname) && is_null($this->basename)) { if (is_null($this->dirname) && is_null($this->basename)) {
$this->setPropertiesEmpty($this->original['width'], $this->original['height']); $this->setPropertiesEmpty($this->original['width'], $this->original['height']);
} else { } else {
@@ -1141,7 +1141,7 @@ class Image
list($r, $g, $b, $alpha) = $value; list($r, $g, $b, $alpha) = $value;
} elseif (count($value) == 3) { } elseif (count($value) == 3) {
// color array without alpha value // color array without alpha value
list($r, $g, $b) = $value; list($r, $g, $b) = $value;
@@ -1205,7 +1205,7 @@ class Image
/** /**
* Convert rgba alpha (0-1) value to gd value (0-127) * Convert rgba alpha (0-1) value to gd value (0-127)
* *
* @param float $input * @param float $input
* @return int * @return int
*/ */
@@ -1223,7 +1223,7 @@ class Image
/** /**
* Convert gd alpha (0-127) value to rgba alpha value (0-1) * Convert gd alpha (0-127) value to rgba alpha value (0-1)
* *
* @param int $input * @param int $input
* @return float * @return float
*/ */

4
tests/ImageTest.php
View File

@@ -386,7 +386,7 @@ class ImageTest extends PHPUnit_Framework_Testcase
$img->flip('h'); $img->flip('h');
$this->assertInstanceOf('Intervention\Image\Image', $img); $this->assertInstanceOf('Intervention\Image\Image', $img);
$this->assertEquals('#ffbf47', $img->pickColor(0, 0, 'hex')); $this->assertEquals('#ffbf47', $img->pickColor(0, 0, 'hex'));
$img = $this->getTestImage(); $img = $this->getTestImage();
$img->flip('v'); $img->flip('v');
$this->assertInstanceOf('Intervention\Image\Image', $img); $this->assertInstanceOf('Intervention\Image\Image', $img);
@@ -515,7 +515,7 @@ class ImageTest extends PHPUnit_Framework_Testcase
$this->assertEquals($checkColor['green'], 0); $this->assertEquals($checkColor['green'], 0);
$this->assertEquals($checkColor['blue'], 0); $this->assertEquals($checkColor['blue'], 0);
$this->assertEquals($checkColor['alpha'], 25); $this->assertEquals($checkColor['alpha'], 25);
} }
public function testPixelateImage() public function testPixelateImage()