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

ImageInterface

interface ImageInterface (View source)

Provides an interface for image objects.

Methods

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.

ImageToolkitInterface
getToolkit()

Returns the image toolkit used for this image file.

string
getToolkitId()

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

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

Applies a toolkit operation to the image.

bool
save(string|null $destination = NULL)

Closes the image and saves the changes to a file.

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

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

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

Scales an image while maintaining aspect ratio.

bool
scaleAndCrop(int $width, int $height)

Scales an image to the exact width and height given.

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
resize(int $width, int $height)

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

bool
desaturate()

Converts an image to grayscale.

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

Rotates an image by the given number of degrees.

Details

at line 16
bool isValid()

Checks if the image is valid.

Return Value

bool

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

at line 24
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 32
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 40
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 49
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 58
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 66
ImageToolkitInterface getToolkit()

Returns the image toolkit used for this image file.

Return Value

ImageToolkitInterface

The image toolkit.

at line 74
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 94
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 108
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.

See also

ImageToolkitInterface::save

at line 131
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 151
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.

at line 170
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 185
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.

See also

ImageToolkitInterface::getSupportedExtensions

at line 202
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 215
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 223
bool desaturate()

Converts an image to grayscale.

Return Value

bool

TRUE on success, FALSE on failure.

at line 240
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) An 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.