1. class
  2. Drupal
  3. \
  4. Core
  5. \
  6. Image
  7. \
  8. Image

Image

class Image implements ImageInterface (View source)

Defines an image object to represent an image file.

Properties

protected string $source

Path of the image file.
protected ImageToolkitInterface $toolkit

An image toolkit object.
protected int $fileSize

File size in bytes.

Methods

__construct(ImageToolkitInterface $toolkit, string|null $source = NULL)

Constructs a new Image object.

bool
isValid()

Checks if the image is valid.

int|null
getHeight()

Returns the height of the image.

int|null
getWidth()

Returns the width of the image.

int|null
getFileSize()

Returns the size of the image file.

string
getMimeType()

Returns the MIME type of the image file.

string
getSource()

Retrieves the source path of the image file.

string
getToolkitId()

Returns the ID of the image toolkit used for this image file.

ImageToolkitInterface
getToolkit()

Returns the image toolkit used for this image file.

bool
save(string|null $destination = NULL)

Closes the image and saves the changes to a file.

bool
apply(string $operation, array $arguments = [])

Applies a toolkit operation to the image.

bool
createNew(int $width, int $height, string $extension = 'png', string $transparent_color = '#ffffff')

Prepares a new image, without loading it from a file.

bool
convert(string $extension)

Instructs the toolkit to save the image in the format specified by the extension.

bool
crop(int $x, int $y, int $width, int $height = NULL)

Crops an image to a rectangle specified by the given dimensions.

bool
desaturate()

Converts an image to grayscale.

bool
resize(int $width, int $height)

Resizes an image to the given dimensions (ignoring aspect ratio).

bool
rotate(float $degrees, string|null $background = NULL)

Rotates an image by the given number of degrees.

bool
scaleAndCrop(int $width, int $height)

Scales an image to the exact width and height given.

bool
scale(int|null $width, int|null $height = NULL, bool $upscale = FALSE)

Scales an image while maintaining aspect ratio.

Details

at line 47
__construct(ImageToolkitInterface $toolkit, string|null $source = NULL)

Constructs a new Image object.

Parameters

ImageToolkitInterface $toolkit

The image toolkit.
string|null $source

(optional) The path to an image file, or NULL to construct the object with no image source.

at line 62
bool isValid()

Checks if the image is valid.

Return Value

bool

TRUE if the image object contains a valid image, FALSE otherwise.

at line 69
int|null getHeight()

Returns the height of the image.

Return Value

int|null

The height of the image, or NULL if the image is invalid.

at line 76
int|null getWidth()

Returns the width of the image.

Return Value

int|null

The width of the image, or NULL if the image is invalid.

at line 83
int|null getFileSize()

Returns the size of the image file.

Return Value

int|null

The size of the file in bytes, or NULL if the image is invalid.

at line 90
string getMimeType()

Returns the MIME type of the image file.

Return Value

string

The MIME type of the image file, or an empty string if the image is invalid.

at line 97
string getSource()

Retrieves the source path of the image file.

Return Value

string

The source path of the image file. An empty string if the source is not set.

at line 104
string getToolkitId()

Returns the ID of the image toolkit used for this image file.

Return Value

string

The ID of the image toolkit.

at line 111
ImageToolkitInterface getToolkit()

Returns the image toolkit used for this image file.

Return Value

ImageToolkitInterface

The image toolkit.

at line 118
bool save(string|null $destination = NULL)

Closes the image and saves the changes to a file.

Parameters

string|null $destination

(optional) Destination path where the image should be saved. If it is empty the original image file will be overwritten.

Return Value

bool

TRUE on success, FALSE on failure.

at line 141
bool apply(string $operation, array $arguments = [])

Applies a toolkit operation to the image.

The operation is deferred to the active toolkit.

Parameters

string $operation

The operation to be performed against the image.
array $arguments

(optional) An associative array of arguments to be passed to the toolkit operation; for instance, @code ['width' => 50, 'height' => 100, 'upscale' => TRUE] @endcode Defaults to an empty array.

Return Value

bool

TRUE on success, FALSE on failure.

at line 148
bool createNew(int $width, int $height, string $extension = 'png', string $transparent_color = '#ffffff')

Prepares a new image, without loading it from a file.

For a working example, see \Drupal\system\Plugin\ImageToolkit\Operation\gd\CreateNew.

Parameters

int $width

The width of the new image, in pixels.
int $height

The height of the new image, in pixels.
string $extension

(optional) The extension of the image file (for instance, 'png', 'gif', etc.). Allowed values depend on the implementation of the image toolkit. Defaults to 'png'.
string $transparent_color

(optional) The hexadecimal string representing the color to be used for transparency, needed for GIF images. Defaults to '#ffffff' (white).

Return Value

bool

TRUE on success, FALSE on failure.

at line 155
bool convert(string $extension)

Instructs the toolkit to save the image in the format specified by the extension.

Parameters

string $extension

The extension to convert to (for instance, 'jpeg' or 'png'). Allowed values depend on the current image toolkit.

Return Value

bool

TRUE on success, FALSE on failure.

at line 162
bool crop(int $x, int $y, int $width, int $height = NULL)

Crops an image to a rectangle specified by the given dimensions.

Parameters

int $x

The top left coordinate, in pixels, of the crop area (x axis value).
int $y

The top left coordinate, in pixels, of the crop area (y axis value).
int $width

The target width, in pixels.
int $height

The target height, in pixels.

Return Value

bool

TRUE on success, FALSE on failure.

at line 169
bool desaturate()

Converts an image to grayscale.

Return Value

bool

TRUE on success, FALSE on failure.

at line 176
bool resize(int $width, int $height)

Resizes an image to the given dimensions (ignoring aspect ratio).

Parameters

int $width

The target width, in pixels.
int $height

The target height, in pixels.

Return Value

bool

TRUE on success, FALSE on failure.

at line 183
bool rotate(float $degrees, string|null $background = NULL)

Rotates an image by the given number of degrees.

Parameters

float $degrees

The number of (clockwise) degrees to rotate the image.
string|null $background

(optional) A hexadecimal integer specifying the background color to use for the uncovered area of the image after the rotation; for example, 0x000000 for black, 0xff00ff for magenta, and 0xffffff for white. When NULL (the default) is specified, for images that support transparency, this will default to transparent; otherwise, it will default to white.

Return Value

bool

TRUE on success, FALSE on failure.

at line 190
bool scaleAndCrop(int $width, int $height)

Scales an image to the exact width and height given.

This function achieves the target aspect ratio by cropping the original image equally on both sides, or equally on the top and bottom. This function is useful to create uniform sized avatars from larger images.

The resulting image always has the exact target dimensions.

Parameters

int $width

The target width, in pixels.
int $height

The target height, in pixels.

Return Value

bool

TRUE on success, FALSE on failure.

at line 197
bool scale(int|null $width, int|null $height = NULL, bool $upscale = FALSE)

Scales an image while maintaining aspect ratio.

The resulting image can be smaller for one or both target dimensions.

Parameters

int|null $width

The target width, in pixels. If this value is null then the scaling will be based only on the height value.
int|null $height

(optional) The target height, in pixels. If this value is null then the scaling will be based only on the width value.
bool $upscale

(optional) Boolean indicating that files smaller than the dimensions will be scaled up. This generally results in a low quality image.

Return Value

bool

TRUE on success, FALSE on failure.