Class Kohana_Image

Kohana_Image

Image manipulation support. Allows images to be resized, cropped, etc.

package
Kohana/Image
category
Base
author
Kohana Team
copyright
(c) Kohana Team
license
https://koseven.ga/LICENSE.md


Constants

Properties

Methods

Constants

NONE

integer 1

WIDTH

integer 2

HEIGHT

integer 3

AUTO

integer 4

INVERSE

integer 5

PRECISE

integer 6

HORIZONTAL

integer 17

VERTICAL

integer 18

IMAGETYPE_WEBP

integer -1

Properties

public static string $default_driver

default driver: GD, ImageMagick, etc

string(2) "GD"

public string $file

image file path

Default value: 
NULL

public integer $height

image height

Default value: 
NULL

public string $mime

mime type of the image

Default value: 
NULL

public integer $type

one of the IMAGETYPE_* constants

Default value: 
NULL

public integer $width

image width

Default value: 
NULL

protected static $_checked

bool FALSE

Methods

public __construct(string $file ) (defined in Kohana_Image)

Loads information about the image. Will throw an exception if the image does not exist or is not an image.

Parameters

  • string $file required - Image file path

Tags

Return Values

  • void

Source Code

public function __construct($file)
{
	try
	{
		// Get the real path to the file
		$file = realpath($file);

		// Get the image information
		$info = getimagesize($file);
	}
	catch (Exception $e)
	{
		// Ignore all errors while reading the image
	}

	if (empty($file) OR empty($info))
	{
		throw new Kohana_Exception('Not an image or invalid image: :file',
			[':file' => Debug::path($file)]);
	}

	// Store the image information
	$this->file   = $file;
	$this->width  = $info[0];
	$this->height = $info[1];
	$this->type   = $info[2];
	$this->mime   = image_type_to_mime_type($this->type);
}

public __toString() (defined in Kohana_Image)

Render the current image.

echo $image;

The output of this function is binary and must be rendered with the appropriate Content-Type header or it will not be displayed correctly!

Return Values

  • string

Source Code

public function __toString()
{
	try
	{
		// Render the current image
		return $this->render();
	}
	catch (Exception $e)
	{
		if (is_object(Kohana::$log))
		{
			// Get the text of the exception
			$error = Kohana_Exception::text($e);

			// Add this exception to the log
			Kohana::$log->add(Log::ERROR, $error);
		}

		// Showing any kind of error will be "inside" image data
		return '';
	}
}

public background(string $color [, integer $opacity = integer 100 ] ) (defined in Kohana_Image)

Set the background color of an image. This is only useful for images with alpha transparency.

// Make the image background black
$image->background('#000');

// Make the image background black with 50% opacity
$image->background('#000', 50);

Parameters

  • string $color required - Hexadecimal color value
  • integer $opacity = integer 100 - Background opacity: 0-100

Tags

Return Values

  • $this

Source Code

public function background($color, $opacity = 100)
{
	if ($color[0] === '#')
	{
		// Remove the pound
		$color = substr($color, 1);
	}

	if (strlen($color) === 3)
	{
		// Convert shorthand into longhand hex notation
		$color = preg_replace('/./', '$0$0', $color);
	}

	// Convert the hex into RGB values
	list ($r, $g, $b) = array_map('hexdec', str_split($color, 2));

	// The opacity must be in the range of 0 to 100
	$opacity = min(max($opacity, 0), 100);

	$this->_do_background($r, $g, $b, $opacity);

	return $this;
}

public crop(integer $width , integer $height [, mixed $offset_x = NULL , mixed $offset_y = NULL ] ) (defined in Kohana_Image)

Crop an image to the given size. Either the width or the height can be omitted and the current width or height will be used.

If no offset is specified, the center of the axis will be used. If an offset of TRUE is specified, the bottom of the axis will be used.

// Crop the image to 200x200 pixels, from the center
$image->crop(200, 200);

Parameters

  • integer $width required - New width
  • integer $height required - New height
  • mixed $offset_x = NULL - Offset from the left
  • mixed $offset_y = NULL - Offset from the top

Tags

Return Values

  • $this

Source Code

public function crop($width, $height, $offset_x = NULL, $offset_y = NULL)
{
	if ($width > $this->width)
	{
		// Use the current width
		$width = $this->width;
	}

	if ($height > $this->height)
	{
		// Use the current height
		$height = $this->height;
	}

	if ($offset_x === NULL)
	{
		// Center the X offset
		$offset_x = round(($this->width - $width) / 2);
	}
	elseif ($offset_x === TRUE)
	{
		// Bottom the X offset
		$offset_x = $this->width - $width;
	}
	elseif ($offset_x < 0)
	{
		// Set the X offset from the right
		$offset_x = $this->width - $width + $offset_x;
	}

	if ($offset_y === NULL)
	{
		// Center the Y offset
		$offset_y = round(($this->height - $height) / 2);
	}
	elseif ($offset_y === TRUE)
	{
		// Bottom the Y offset
		$offset_y = $this->height - $height;
	}
	elseif ($offset_y < 0)
	{
		// Set the Y offset from the bottom
		$offset_y = $this->height - $height + $offset_y;
	}

	// Determine the maximum possible width and height
	$max_width  = $this->width  - $offset_x;
	$max_height = $this->height - $offset_y;

	if ($width > $max_width)
	{
		// Use the maximum available width
		$width = $max_width;
	}

	if ($height > $max_height)
	{
		// Use the maximum available height
		$height = $max_height;
	}

	$this->_do_crop($width, $height, $offset_x, $offset_y);

	return $this;
}

public static factory(string $file [, string $driver = NULL ] ) (defined in Kohana_Image)

Loads an image and prepares it for manipulation.

$image = Image::factory('upload/test.jpg');

Parameters

  • string $file required - Image file path
  • string $driver = NULL - Driver type: GD, ImageMagick, etc

Tags

Return Values

  • Image

Source Code

public static function factory($file, $driver = NULL)
{
	if ($driver === NULL)
	{
		// Use the driver from configuration file or default one
		$configured_driver = Kohana::$config->load('image.default_driver');
		$driver = ($configured_driver) ? $configured_driver : Image::$default_driver;
	}

	// Set the class name
	$class = 'Image_'.$driver;

	return new $class($file);
}

public flip(integer $direction ) (defined in Kohana_Image)

Flip the image along the horizontal or vertical axis.

// Flip the image from top to bottom
$image->flip(Image::HORIZONTAL);

// Flip the image from left to right
$image->flip(Image::VERTICAL);

Parameters

  • integer $direction required - Direction: Image::HORIZONTAL, Image::VERTICAL

Tags

Return Values

  • $this

Source Code

public function flip($direction)
{
	if ($direction !== Image::HORIZONTAL)
	{
		// Flip vertically
		$direction = Image::VERTICAL;
	}

	$this->_do_flip($direction);

	return $this;
}

public reflection([ integer $height = NULL , integer $opacity = integer 100 , boolean $fade_in = bool FALSE ] ) (defined in Kohana_Image)

Add a reflection to an image. The most opaque part of the reflection will be equal to the opacity setting and fade out to full transparent. Alpha transparency is preserved.

// Create a 50 pixel reflection that fades from 0-100% opacity
$image->reflection(50);

// Create a 50 pixel reflection that fades from 100-0% opacity
$image->reflection(50, 100, TRUE);

// Create a 50 pixel reflection that fades from 0-60% opacity
$image->reflection(50, 60, TRUE);

By default, the reflection will be go from transparent at the top to opaque at the bottom.

Parameters

  • integer $height = NULL - Reflection height
  • integer $opacity = integer 100 - Reflection opacity: 0-100
  • boolean $fade_in = bool FALSE - TRUE to fade in, FALSE to fade out

Tags

Return Values

  • $this

Source Code

public function reflection($height = NULL, $opacity = 100, $fade_in = FALSE)
{
	if ($height === NULL OR $height > $this->height)
	{
		// Use the current height
		$height = $this->height;
	}

	// The opacity must be in the range of 0 to 100
	$opacity = min(max($opacity, 0), 100);

	$this->_do_reflection($height, $opacity, $fade_in);

	return $this;
}

public render([ string $type = NULL , integer $quality = integer 100 ] ) (defined in Kohana_Image)

Render the image and return the binary string.

// Render the image at 50% quality
$data = $image->render(NULL, 50);

// Render the image as a PNG
$data = $image->render('png');

Parameters

  • string $type = NULL - Image type to return: png, jpg, gif, etc
  • integer $quality = integer 100 - Quality of image: 1-100

Tags

Return Values

  • string

Source Code

public function render($type = NULL, $quality = 100)
{
	if ($type === NULL)
	{
		// Use the current image type
		$type = image_type_to_extension($this->type, FALSE);
	}

	return $this->_do_render($type, $quality);
}

public resize([ integer $width = NULL , integer $height = NULL , integer $master = NULL ] ) (defined in Kohana_Image)

Resize the image to the given size. Either the width or the height can be omitted and the image will be resized proportionally.

// Resize to 200 pixels on the shortest side
$image->resize(200, 200);

// Resize to 200x200 pixels, keeping aspect ratio
$image->resize(200, 200, Image::INVERSE);

// Resize to 500 pixel width, keeping aspect ratio
$image->resize(500, NULL);

// Resize to 500 pixel height, keeping aspect ratio
$image->resize(NULL, 500);

// Resize to 200x500 pixels, ignoring aspect ratio
$image->resize(200, 500, Image::NONE);

Parameters

  • integer $width = NULL - New width
  • integer $height = NULL - New height
  • integer $master = NULL - Master dimension

Tags

Return Values

  • $this

Source Code

public function resize($width = NULL, $height = NULL, $master = NULL)
{
	if ($master === NULL)
	{
		// Choose the master dimension automatically
		$master = Image::AUTO;
	}
	// Image::WIDTH and Image::HEIGHT deprecated. You can use it in old projects,
	// but in new you must pass empty value for non-master dimension
	elseif ($master == Image::WIDTH AND ! empty($width))
	{
		$master = Image::AUTO;

		// Set empty height for backward compatibility
		$height = NULL;
	}
	elseif ($master == Image::HEIGHT AND ! empty($height))
	{
		$master = Image::AUTO;

		// Set empty width for backward compatibility
		$width = NULL;
	}

	if (empty($width))
	{
		if ($master === Image::NONE)
		{
			// Use the current width
			$width = $this->width;
		}
		else
		{
			// If width not set, master will be height
			$master = Image::HEIGHT;
		}
	}

	if (empty($height))
	{
		if ($master === Image::NONE)
		{
			// Use the current height
			$height = $this->height;
		}
		else
		{
			// If height not set, master will be width
			$master = Image::WIDTH;
		}
	}

	switch ($master)
	{
		case Image::AUTO:
			// Choose direction with the greatest reduction ratio
			$master = ($this->width / $width) > ($this->height / $height) ? Image::WIDTH : Image::HEIGHT;
		break;
		case Image::INVERSE:
			// Choose direction with the minimum reduction ratio
			$master = ($this->width / $width) > ($this->height / $height) ? Image::HEIGHT : Image::WIDTH;
		break;
	}

	switch ($master)
	{
		case Image::WIDTH:
			// Recalculate the height based on the width proportions
			$height = $this->height * $width / $this->width;
		break;
		case Image::HEIGHT:
			// Recalculate the width based on the height proportions
			$width = $this->width * $height / $this->height;
		break;
		case Image::PRECISE:
			// Resize to precise size
			$ratio = $this->width / $this->height;

			if ($width / $height > $ratio)
			{
				$height = $this->height * $width / $this->width;
			}
			else
			{
				$width = $this->width * $height / $this->height;
			}
		break;
	}

	// Convert the width and height to integers, minimum value is 1px
	$width  = max(round($width), 1);
	$height = max(round($height), 1);

	$this->_do_resize($width, $height);

	return $this;
}

public rotate(integer $degrees ) (defined in Kohana_Image)

Rotate the image by a given amount.

// Rotate 45 degrees clockwise
$image->rotate(45);

// Rotate 90% counter-clockwise
$image->rotate(-90);

Parameters

  • integer $degrees required - Degrees to rotate: -360-360

Tags

Return Values

  • $this

Source Code

public function rotate($degrees)
{
	// Make the degrees an integer
	$degrees = (int) $degrees;

	if ($degrees > 180)
	{
		do
		{
			// Keep subtracting full circles until the degrees have normalized
			$degrees -= 360;
		}
		while ($degrees > 180);
	}

	if ($degrees < -180)
	{
		do
		{
			// Keep adding full circles until the degrees have normalized
			$degrees += 360;
		}
		while ($degrees < -180);
	}

	$this->_do_rotate($degrees);

	return $this;
}

public save([ string $file = NULL , integer $quality = integer 100 ] ) (defined in Kohana_Image)

Save the image. If the filename is omitted, the original image will be overwritten.

// Save the image as a PNG
$image->save('saved/cool.png');

// Overwrite the original image
$image->save();

If the file exists, but is not writable, an exception will be thrown.

If the file does not exist, and the directory is not writable, an exception will be thrown.

Parameters

  • string $file = NULL - New image path
  • integer $quality = integer 100 - Quality of image: 1-100

Tags

Return Values

  • boolean

Source Code

public function save($file = NULL, $quality = 100)
{
	if ($file === NULL)
	{
		// Overwrite the file
		$file = $this->file;
	}

	if (is_file($file))
	{
		if ( ! is_writable($file))
		{
			throw new Kohana_Exception('File must be writable: :file',
				[':file' => Debug::path($file)]);
		}
	}
	else
	{
		// Get the directory of the file
		$directory = realpath(pathinfo($file, PATHINFO_DIRNAME));

		if ( ! is_dir($directory) OR ! is_writable($directory))
		{
			throw new Kohana_Exception('Directory must be writable: :directory',
				[':directory' => Debug::path($directory)]);
		}
	}

	// The quality must be in the range of 1 to 100
	$quality = min(max($quality, 1), 100);

	return $this->_do_save($file, $quality);
}

public sharpen(integer $amount ) (defined in Kohana_Image)

Sharpen the image by a given amount.

// Sharpen the image by 20%
$image->sharpen(20);

Parameters

  • integer $amount required - Amount to sharpen: 1-100

Tags

Return Values

  • $this

Source Code

public function sharpen($amount)
{
	// The amount must be in the range of 1 to 100
	$amount = min(max($amount, 1), 100);

	$this->_do_sharpen($amount);

	return $this;
}

public watermark(Image $watermark [, integer $offset_x = NULL , integer $offset_y = NULL , integer $opacity = integer 100 ] ) (defined in Kohana_Image)

Add a watermark to an image with a specified opacity. Alpha transparency will be preserved.

If no offset is specified, the center of the axis will be used. If an offset of TRUE is specified, the bottom of the axis will be used.

// Add a watermark to the bottom right of the image
$mark = Image::factory('upload/watermark.png');
$image->watermark($mark, TRUE, TRUE);

Parameters

  • Image $watermark required - Watermark Image instance
  • integer $offset_x = NULL - Offset from the left
  • integer $offset_y = NULL - Offset from the top
  • integer $opacity = integer 100 - Opacity of watermark: 1-100

Tags

Return Values

  • $this

Source Code

public function watermark(Image $watermark, $offset_x = NULL, $offset_y = NULL, $opacity = 100)
{
	if ($offset_x === NULL)
	{
		// Center the X offset
		$offset_x = round(($this->width - $watermark->width) / 2);
	}
	elseif ($offset_x === TRUE)
	{
		// Bottom the X offset
		$offset_x = $this->width - $watermark->width;
	}
	elseif ($offset_x < 0)
	{
		// Set the X offset from the right
		$offset_x = $this->width - $watermark->width + $offset_x;
	}

	if ($offset_y === NULL)
	{
		// Center the Y offset
		$offset_y = round(($this->height - $watermark->height) / 2);
	}
	elseif ($offset_y === TRUE)
	{
		// Bottom the Y offset
		$offset_y = $this->height - $watermark->height;
	}
	elseif ($offset_y < 0)
	{
		// Set the Y offset from the bottom
		$offset_y = $this->height - $watermark->height + $offset_y;
	}

	// The opacity must be in the range of 1 to 100
	$opacity = min(max($opacity, 1), 100);

	$this->_do_watermark($watermark, $offset_x, $offset_y, $opacity);

	return $this;
}

abstract protected _do_background(integer $r , integer $g , integer $b , integer $opacity ) (defined in Kohana_Image)

Execute a background.

Parameters

  • integer $r required - Red
  • integer $g required - Green
  • integer $b required - Blue
  • integer $opacity required - Opacity

Return Values

  • void

Source Code

abstract protected function _do_background($r, $g, $b, $opacity);

abstract protected _do_crop(integer $width , integer $height , integer $offset_x , integer $offset_y ) (defined in Kohana_Image)

Execute a crop.

Parameters

  • integer $width required - New width
  • integer $height required - New height
  • integer $offset_x required - Offset from the left
  • integer $offset_y required - Offset from the top

Return Values

  • void

Source Code

abstract protected function _do_crop($width, $height, $offset_x, $offset_y);

abstract protected _do_flip(integer $direction ) (defined in Kohana_Image)

Execute a flip.

Parameters

  • integer $direction required - Direction to flip

Return Values

  • void

Source Code

abstract protected function _do_flip($direction);

abstract protected _do_reflection(integer $height , integer $opacity , boolean $fade_in ) (defined in Kohana_Image)

Execute a reflection.

Parameters

  • integer $height required - Reflection height
  • integer $opacity required - Reflection opacity
  • boolean $fade_in required - TRUE to fade out, FALSE to fade in

Return Values

  • void

Source Code

abstract protected function _do_reflection($height, $opacity, $fade_in);

abstract protected _do_render(string $type , integer $quality ) (defined in Kohana_Image)

Execute a render.

Parameters

  • string $type required - Image type: png, jpg, gif, etc
  • integer $quality required - Quality

Return Values

  • string

Source Code

abstract protected function _do_render($type, $quality);

abstract protected _do_resize(integer $width , integer $height ) (defined in Kohana_Image)

Execute a resize.

Parameters

  • integer $width required - New width
  • integer $height required - New height

Return Values

  • void

Source Code

abstract protected function _do_resize($width, $height);

abstract protected _do_rotate(integer $degrees ) (defined in Kohana_Image)

Execute a rotation.

Parameters

  • integer $degrees required - Degrees to rotate

Return Values

  • void

Source Code

abstract protected function _do_rotate($degrees);

abstract protected _do_save(string $file , integer $quality ) (defined in Kohana_Image)

Execute a save.

Parameters

  • string $file required - New image filename
  • integer $quality required - Quality

Return Values

  • boolean

Source Code

abstract protected function _do_save($file, $quality);

abstract protected _do_sharpen(integer $amount ) (defined in Kohana_Image)

Execute a sharpen.

Parameters

  • integer $amount required - Amount to sharpen

Return Values

  • void

Source Code

abstract protected function _do_sharpen($amount);

abstract protected _do_watermark(Image $image , integer $offset_x , integer $offset_y , integer $opacity ) (defined in Kohana_Image)

Execute a watermarking.

Parameters

  • Image $image required - Watermarking Image
  • integer $offset_x required - Offset from the left
  • integer $offset_y required - Offset from the top
  • integer $opacity required - Opacity of watermark

Return Values

  • void

Source Code

abstract protected function _do_watermark(Image $image, $offset_x, $offset_y, $opacity);

protected image_type_to_mime_type(string $type ) (defined in Kohana_Image)

Returns the image mime type Adds support for webp image type, which is not known by php

Parameters

  • string $type required - Image type: png, jpg, gif, etc

Return Values

  • string

Source Code

protected function image_type_to_mime_type($type)
{
	if ($type === self::IMAGETYPE_WEBP)
		return 'image/webp';

	return image_type_to_mime_type($type);
}

Modules

Do you want to contribute to Koseven?

Koseven Logo

We need YOUR help!

This project is open source. What does this mean? YOU can help:
  • Found a bug? Report it on Github
  • Need a feature? Add it Here
  • Want to help? Join the Forum
Go to Github