mirror/intervention_image
1
0
Fork 0
mirror of https://github.com/Intervention/image.git synced 2025-08-17 19:26:25 +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 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.
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/).
[Intervention Image Class Documentation](http://intervention.olivervogel.net/image/)
## License
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",
"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"],
"license": "MIT",
"authors": [

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

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

4
tests/ImageTest.php
View File

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