Class yii\imagine\BaseImage
Inheritance | yii\imagine\BaseImage |
---|---|
Subclasses | yii\imagine\Image |
Available since extension's version | 2.0 |
Source Code | https://github.com/yiisoft/yii2-imagine/blob/master/BaseImage.php |
BaseImage provides concrete implementation for yii\imagine\Image.
Do not use BaseImage. Use yii\imagine\Image instead.
Public Properties
Property | Type | Description | Defined By |
---|---|---|---|
$driver | array|string | The driver to use. | yii\imagine\BaseImage |
$thumbnailBackgroundAlpha | string | Background alpha (transparency) to use when creating thumbnails in ImageInterface::THUMBNAIL_INSET mode with both width and height specified. |
yii\imagine\BaseImage |
$thumbnailBackgroundColor | string | Background color to use when creating thumbnails in ImageInterface::THUMBNAIL_INSET mode with both width and height specified. |
yii\imagine\BaseImage |
Public Methods
Method | Description | Defined By |
---|---|---|
crop() | Crops an image. | yii\imagine\BaseImage |
frame() | Adds a frame around of the image. Please note that the image size will increase by $margin x 2. |
yii\imagine\BaseImage |
getImagine() | Returns the Imagine object that supports various image manipulations. |
yii\imagine\BaseImage |
setImagine() | yii\imagine\BaseImage | |
text() | Draws a text string on an existing image. | yii\imagine\BaseImage |
thumbnail() | Creates a thumbnail image. | yii\imagine\BaseImage |
watermark() | Adds a watermark to an existing image. | yii\imagine\BaseImage |
Protected Methods
Method | Description | Defined By |
---|---|---|
createImagine() | Creates an Imagine object based on the specified $driver. |
yii\imagine\BaseImage |
getThumbnailBox() | Returns box for a thumbnail to be created. If one of the dimensions is set to null , another one is calculated
automatically based on width to height ratio of original image box. |
yii\imagine\BaseImage |
Constants
Constant | Value | Description | Defined By |
---|---|---|---|
DRIVER_GD2 | 'gd2' | GD2 driver definition for Imagine implementation using the GD library. | yii\imagine\BaseImage |
DRIVER_GMAGICK | 'gmagick' | Gmagick driver definition. | yii\imagine\BaseImage |
DRIVER_IMAGICK | 'imagick' | Imagick driver definition. | yii\imagine\BaseImage |
Property Details
The driver to use. This can be either a single driver name or an array of driver names. If the latter, the first available driver will be used.
Background alpha (transparency) to use when creating thumbnails in ImageInterface::THUMBNAIL_INSET
mode with both width and height specified. Default is solid.
Background color to use when creating thumbnails in ImageInterface::THUMBNAIL_INSET
mode with
both width and height specified. Default is white.
Method Details
Creates an Imagine
object based on the specified $driver.
protected static \Imagine\Image\ImagineInterface createImagine ( ) | ||
return | \Imagine\Image\ImagineInterface |
The new |
---|---|---|
throws | \yii\base\InvalidConfigException |
if $driver is unknown or the system doesn't support any $driver. |
protected static function createImagine()
{
foreach ((array) static::$driver as $driver) {
switch ($driver) {
case self::DRIVER_GMAGICK:
if (class_exists('Gmagick', false)) {
return new \Imagine\Gmagick\Imagine();
}
break;
case self::DRIVER_IMAGICK:
if (class_exists('Imagick', false)) {
return new \Imagine\Imagick\Imagine();
}
break;
case self::DRIVER_GD2:
if (function_exists('gd_info')) {
return new \Imagine\Gd\Imagine();
}
break;
default:
throw new InvalidConfigException("Unknown driver: $driver");
}
}
throw new InvalidConfigException("Your system does not support any of these drivers: " . implode(',', (array) static::$driver));
}
Crops an image.
For example,
$obj->crop('path\to\image.jpg', 200, 200, [5, 5]);
$point = new \Imagine\Image\Point(5, 5);
$obj->crop('path\to\image.jpg', 200, 200, $point);
public static \Imagine\Image\ImageInterface crop ( $filename, $width, $height, array $start = [0, 0] ) | ||
$filename | string |
The image file path or path alias. |
$width | integer |
The crop width |
$height | integer |
The crop height |
$start | array |
The starting point. This must be an array with two elements representing |
throws | \yii\base\InvalidParamException |
if the |
---|
public static function crop($filename, $width, $height, array $start = [0, 0])
{
if (!isset($start[0], $start[1])) {
throw new InvalidParamException('$start must be an array of two elements.');
}
return static::getImagine()
->open(Yii::getAlias($filename))
->copy()
->crop(new Point($start[0], $start[1]), new Box($width, $height));
}
Adds a frame around of the image. Please note that the image size will increase by $margin
x 2.
public static \Imagine\Image\ImageInterface frame ( $filename, $margin = 20, $color = '666', $alpha = 100 ) | ||
$filename | string |
The full path to the image file |
$margin | integer |
The frame size to add around the image |
$color | string |
The frame color |
$alpha | integer |
The alpha value of the frame. |
public static function frame($filename, $margin = 20, $color = '666', $alpha = 100)
{
$img = static::getImagine()->open(Yii::getAlias($filename));
$size = $img->getSize();
$pasteTo = new Point($margin, $margin);
$padColor = new Color($color, $alpha);
$box = new Box($size->getWidth() + ceil($margin * 2), $size->getHeight() + ceil($margin * 2));
$image = static::getImagine()->create($box, $padColor);
$image->paste($img, $pasteTo);
return $image;
}
Returns the Imagine
object that supports various image manipulations.
public static \Imagine\Image\ImagineInterface getImagine ( ) | ||
return | \Imagine\Image\ImagineInterface |
The |
---|
public static function getImagine()
{
if (self::$_imagine === null) {
self::$_imagine = static::createImagine();
}
return self::$_imagine;
}
Returns box for a thumbnail to be created. If one of the dimensions is set to null
, another one is calculated
automatically based on width to height ratio of original image box.
protected static \Imagine\Image\BoxInterface getThumbnailBox ( \Imagine\Image\BoxInterface $sourceBox, $width, $height ) | ||
$sourceBox | \Imagine\Image\BoxInterface |
Original image box |
$width | integer |
Thumbnail width |
$height | integer |
Thumbnail height |
return | \Imagine\Image\BoxInterface |
Thumbnail box |
---|
protected static function getThumbnailBox(BoxInterface $sourceBox, $width, $height)
{
if ($width !== null && $height !== null) {
return new Box($width, $height);
}
if ($width === null && $height === null) {
throw new InvalidParamException('Width and height cannot be null at same time.');
}
$ratio = $sourceBox->getWidth() / $sourceBox->getHeight();
if ($height === null) {
$height = ceil($width / $ratio);
} else {
$width = ceil($height * $ratio);
}
return new Box($width, $height);
}
public static void setImagine ( $imagine ) | ||
$imagine | \Imagine\Image\ImagineInterface |
The |
public static function setImagine($imagine)
{
self::$_imagine = $imagine;
}
Draws a text string on an existing image.
public static \Imagine\Image\ImageInterface text ( $filename, $text, $fontFile, array $start = [0, 0], array $fontOptions = [] ) | ||
$filename | string |
The image file path or path alias. |
$text | string |
The text to write to the image |
$fontFile | string |
The file path or path alias |
$start | array |
The starting position of the text. This must be an array with two elements representing |
$fontOptions | array |
The font options. The following options may be specified:
|
throws | \yii\base\InvalidParamException |
if |
---|
public static function text($filename, $text, $fontFile, array $start = [0, 0], array $fontOptions = [])
{
if (!isset($start[0], $start[1])) {
throw new InvalidParamException('$start must be an array of two elements.');
}
$fontSize = ArrayHelper::getValue($fontOptions, 'size', 12);
$fontColor = ArrayHelper::getValue($fontOptions, 'color', 'fff');
$fontAngle = ArrayHelper::getValue($fontOptions, 'angle', 0);
$img = static::getImagine()->open(Yii::getAlias($filename));
$font = static::getImagine()->font(Yii::getAlias($fontFile), $fontSize, new Color($fontColor));
$img->draw()->text($text, $font, new Point($start[0], $start[1]), $fontAngle);
return $img;
}
Creates a thumbnail image.
If one of thumbnail dimensions is set to null
, another one is calculated automatically based on aspect ratio of
original image. Note that calculated thumbnail dimension may vary depending on the source image in this case.
If both dimensions are specified, resulting thumbnail would be exactly the width and height specified. How it's achieved depends on the mode.
If ImageInterface::THUMBNAIL_OUTBOUND
mode is used, which is default, then the thumbnail is scaled so that
its smallest side equals the length of the corresponding side in the original image. Any excess outside of
the scaled thumbnail’s area will be cropped, and the returned thumbnail will have the exact width and height
specified.
If thumbnail mode is ImageInterface::THUMBNAIL_INSET
, the original image is scaled down so it is fully
contained within the thumbnail dimensions. The rest is filled with background that could be configured via
yii\imagine\Image::$thumbnailBackgroundColor and yii\imagine\Image::$thumbnailBackgroundAlpha.
public static \Imagine\Image\ImageInterface thumbnail ( $filename, $width, $height, $mode = ManipulatorInterface::THUMBNAIL_OUTBOUND ) | ||
$filename | string |
The image file path or path alias. |
$width | integer |
The width in pixels to create the thumbnail |
$height | integer |
The height in pixels to create the thumbnail |
$mode | string |
Mode of resizing original image to use in case both width and height specified |
public static function thumbnail($filename, $width, $height, $mode = ManipulatorInterface::THUMBNAIL_OUTBOUND)
{
$img = static::getImagine()->open(Yii::getAlias($filename));
$sourceBox = $img->getSize();
$thumbnailBox = static::getThumbnailBox($sourceBox, $width, $height);
if (($sourceBox->getWidth() <= $thumbnailBox->getWidth() && $sourceBox->getHeight() <= $thumbnailBox->getHeight()) || (!$thumbnailBox->getWidth() && !$thumbnailBox->getHeight())) {
return $img->copy();
}
$img = $img->thumbnail($thumbnailBox, $mode);
if ($mode == ManipulatorInterface::THUMBNAIL_OUTBOUND) {
return $img;
}
$size = $img->getSize();
if ($size->getWidth() == $width && $size->getHeight() == $height) {
return $img;
}
// create empty image to preserve aspect ratio of thumbnail
$thumb = static::getImagine()->create($thumbnailBox, new Color(static::$thumbnailBackgroundColor, static::$thumbnailBackgroundAlpha));
// calculate points
$startX = 0;
$startY = 0;
if ($size->getWidth() < $width) {
$startX = ceil($width - $size->getWidth()) / 2;
}
if ($size->getHeight() < $height) {
$startY = ceil($height - $size->getHeight()) / 2;
}
$thumb->paste($img, new Point($startX, $startY));
return $thumb;
}
Adds a watermark to an existing image.
public static \Imagine\Image\ImageInterface watermark ( $filename, $watermarkFilename, array $start = [0, 0] ) | ||
$filename | string |
The image file path or path alias. |
$watermarkFilename | string |
The file path or path alias of the watermark image. |
$start | array |
The starting point. This must be an array with two elements representing |
throws | \yii\base\InvalidParamException |
if |
---|
public static function watermark($filename, $watermarkFilename, array $start = [0, 0])
{
if (!isset($start[0], $start[1])) {
throw new InvalidParamException('$start must be an array of two elements.');
}
$img = static::getImagine()->open(Yii::getAlias($filename));
$watermark = static::getImagine()->open(Yii::getAlias($watermarkFilename));
$img->paste($watermark, new Point($start[0], $start[1]));
return $img;
}