Image
in package
Represents an image and allows low-level graphics operations to be performed, specially as needed for avatars, attachments, etc.
Table of Contents
Constants
- DEFAULT_IMAGETYPE = IMAGETYPE_JPEG
- IMAGETYPE_TO_IMAGICK = [IMAGETYPE_BMP => 'bmp', IMAGETYPE_GIF => 'gif', IMAGETYPE_ICO => 'ico', IMAGETYPE_JP2 => 'jp2', IMAGETYPE_JPEG => 'jpeg', IMAGETYPE_JPEG2000 => 'jp2', IMAGETYPE_PNG => 'png', IMAGETYPE_PSD => 'psd', IMAGETYPE_TIFF_II => 'tiff', IMAGETYPE_TIFF_MM => 'tiff', IMAGETYPE_WBMP => 'wbmp', IMAGETYPE_WEBP => 'webp', IMAGETYPE_XBM => 'xbm', IMAGETYPE_AVIF => 'avif']
Properties
- $embedded_thumb : bool
- $filesize : int
- $height : int
- $image_types : array<string|int, mixed>
- $is_temp : bool
- $mime_type : string
- $orientation : int
- $original : string
- $pathinfo : array<string|int, mixed>
- $source : string
- $supported : array<string|int, mixed>
- $type : int
- $width : int|float
- $force_resize : bool
Methods
- __construct() : mixed
- Constructor.
- check() : bool
- Searches through the file to see if there's potentially harmful content.
- checkMemory() : bool
- Check whether we have enough memory to make a thumbnail.
- createThumbnail() : object|bool
- Create a thumbnail of the given source file.
- getImageTypes() : array<string|int, mixed>
- Get all the IMAGETYPE_* constants defined by this version of PHP.
- getSizeExternal() : array<string|int, mixed>|false
- Get the size of an external image.
- getSupportedFormats() : array<string|int, mixed>
- Get all the image formats supported by the installed graphics library.
- gifOutputAsPng() : bool
- Writes a GIF file to disk as a PNG file.
- move() : bool
- Moves the image file to a new location and updates properties to match.
- reencode() : bool
- Re-encodes an image to a specified image format.
- resize() : bool
- Resizes an image from a remote location or a local file.
- shouldResize() : bool
- Checks whether the image should be resized in order to fit the specified dimensions.
- checkForEmbeddedThumb() : void
- Sets $this->embedded_thumb to true if there is an embedded thumbnail in this image, or false if there isn't.
- checkRaster() : bool
- Searches through a raster image to see if it contains potentially harmful content.
- checkSvg() : bool
- Searches through an SVG image to see if it contains potentially harmful content.
- getDimensionsAndOrientation() : void
- Sets $this->width, $this->height, and $this->orientation.
- getImageType() : void
- Sets $this->type to the value of an IMAGETYPE_* constant.
- getSvgDimensions() : void
- Sets $this->width and $this->height for SVG files.
- mimeTypeToImageType() : int
- Gets the IMAGETYPE_* constant corresponding to the passed MIME type.
- resizeUsingGD() : bool
- Resizes an image using the GD extension.
- resizeUsingImagick() : bool
- Resizes an image using the imagick extension.
Constants
DEFAULT_IMAGETYPE
public
mixed
DEFAULT_IMAGETYPE
= IMAGETYPE_JPEG
IMAGETYPE_TO_IMAGICK
public
mixed
IMAGETYPE_TO_IMAGICK
= [IMAGETYPE_BMP => 'bmp', IMAGETYPE_GIF => 'gif', IMAGETYPE_ICO => 'ico', IMAGETYPE_JP2 => 'jp2', IMAGETYPE_JPEG => 'jpeg', IMAGETYPE_JPEG2000 => 'jp2', IMAGETYPE_PNG => 'png', IMAGETYPE_PSD => 'psd', IMAGETYPE_TIFF_II => 'tiff', IMAGETYPE_TIFF_MM => 'tiff', IMAGETYPE_WBMP => 'wbmp', IMAGETYPE_WEBP => 'webp', IMAGETYPE_XBM => 'xbm', IMAGETYPE_AVIF => 'avif']
Properties
$embedded_thumb
public
bool
$embedded_thumb
= false
Whether this image has an embedded thumbnail.
$filesize
public
int
$filesize
= 0
Size of the image file, in bytes.
$height
public
int
$height
Height of the image in pixels.
Can be a float if an SVG has undefined (i.e. infinite) height.
$image_types
public
static array<string|int, mixed>
$image_types
All IMAGETYPE_* constants known by this version of PHP.
Keys are the string names of the constants. Values are the literal integer values of those constants.
$is_temp
public
bool
$is_temp
Whether the source file is a temporary file.
$mime_type
public
string
$mime_type
MIME type of the image.
$orientation
public
int
$orientation
= 0
Orientation of the image.
$original
public
string
$original
Path or URL to the original source file.
Stays the same even when $source changes due to a resize, reencode, etc.
If the object was constructed from raw image data, this will be the path to the temporary file that was initially created for it.
$pathinfo
public
array<string|int, mixed>
$pathinfo
Path info for the source file.
$source
public
string
$source
Path to the source file.
$supported
public
static array<string|int, mixed>
$supported
Raster image types that are fully supported both by this class and by the installed graphics library.
Values are the integer values of IMAGETYPE_* constants.
$type
public
int
$type
IMAGETYPE_* value for the image.
$width
public
int|float
$width
Width of the image in pixels.
Can be a float if an SVG has undefined (i.e. infinite) width.
$force_resize
protected
bool
$force_resize
= false
Whether to force resizing even if the image is already small enough. This is used by the reencode() method.
Methods
__construct()
Constructor.
public
__construct(mixed $source[, mixed $strict = false ]) : mixed
If $source is a local file, it will be used as-is.
If $source is a URL, it will be downloaded, validated, and saved to a temporary local file.
If $source contains raw image data, it will be validated and then saved to a temporary local file.
Parameters
- $source : mixed
-
Either the path or URL of an image, or raw image data.
- $strict : mixed = false
-
If true, die with error if $source is not a valid image. If false, silently set properties to empty values. Default: false.
check()
Searches through the file to see if there's potentially harmful content.
public
check([bool $extensive = false ]) : bool
Parameters
- $extensive : bool = false
-
Whether to perform extensive checks.
Return values
bool —Whether the image appears to be safe.
checkMemory()
Check whether we have enough memory to make a thumbnail.
public
static checkMemory(array<string|int, mixed> $sizes) : bool
Parameters
- $sizes : array<string|int, mixed>
-
Image size.
Return values
bool —Whether we do.
createThumbnail()
Create a thumbnail of the given source file.
public
createThumbnail(int $max_width, int $max_height) : object|bool
Parameters
- $max_width : int
-
The maximum allowed width.
- $max_height : int
-
The maximum allowed height.
Return values
object|bool —An instance of this class for the thumbnail image, or false on failure.
getImageTypes()
Get all the IMAGETYPE_* constants defined by this version of PHP.
public
static getImageTypes() : array<string|int, mixed>
Return values
array<string|int, mixed> —List of IMAGETYPE_* constant names and values.
getSizeExternal()
Get the size of an external image.
public
static getSizeExternal(string $url) : array<string|int, mixed>|false
Parameters
- $url : string
-
The URL of the image.
Return values
array<string|int, mixed>|false —Width and height, or false on failure.
getSupportedFormats()
Get all the image formats supported by the installed graphics library.
public
static getSupportedFormats() : array<string|int, mixed>
Return values
array<string|int, mixed> —List of supported image formats.
gifOutputAsPng()
Writes a GIF file to disk as a PNG file.
public
static gifOutputAsPng(File $gif, string $lpszFileName[, string $background_color = '-1' ]) : bool
This is unused by SMF itself, but retained for compatibility with any mods that use it.
Parameters
- $gif : File
-
A GIF image resource.
- $lpszFileName : string
-
The name of the file.
- $background_color : string = '-1'
-
The background color.
Return values
bool —Whether the operation was successful.
move()
Moves the image file to a new location and updates properties to match.
public
move(string $destination) : bool
Parameters
- $destination : string
-
Path to new file location.
Return values
bool —Whether the operation was successful.
reencode()
Re-encodes an image to a specified image format.
public
reencode([int $preferred_type = 0 ]) : bool
Creates a copy of the file at the same location as the original, except with the appropriate file extension for the new format, and then removes the original file.
Parameters
- $preferred_type : int = 0
-
And IMAGETYPE_* constant, or 0 for automatic.
Return values
bool —Whether the reencoding operation was successful.
resize()
Resizes an image from a remote location or a local file.
public
resize(string $destination, int $max_width, int $max_height[, int &$preferred_type = 0 ]) : bool
Puts the resized image at the destination location.
$preferred_type is passed by reference. If the preferred type is not a supported image type, it will be changed to reflect the IMAGETYPE_* value that was actually used.
Parameters
- $destination : string
-
The path to the destination image.
- $max_width : int
-
The maximum allowed width.
- $max_height : int
-
The maximum allowed height.
- $preferred_type : int = 0
-
And IMAGETYPE_* constant, or 0 for automatic.
Return values
bool —Whether it succeeded.
shouldResize()
Checks whether the image should be resized in order to fit the specified dimensions.
public
shouldResize(int $max_width, int $max_height) : bool
Zeroes in either argument will be treated as INF.
Parameters
- $max_width : int
-
Maximum allowed width.
- $max_height : int
-
Maximum allowed height.
Return values
bool —Whether the image fits within the specified dimensions.
checkForEmbeddedThumb()
Sets $this->embedded_thumb to true if there is an embedded thumbnail in this image, or false if there isn't.
protected
checkForEmbeddedThumb() : void
checkRaster()
Searches through a raster image to see if it contains potentially harmful content.
protected
checkRaster([bool $extensive = false ]) : bool
Parameters
- $extensive : bool = false
-
Whether to perform extensive checks.
Return values
bool —Whether the image appears to be safe.
checkSvg()
Searches through an SVG image to see if it contains potentially harmful content.
protected
checkSvg() : bool
Return values
bool —Whether the image appears to be safe.
getDimensionsAndOrientation()
Sets $this->width, $this->height, and $this->orientation.
protected
getDimensionsAndOrientation() : void
getImageType()
Sets $this->type to the value of an IMAGETYPE_* constant.
protected
getImageType() : void
getSvgDimensions()
Sets $this->width and $this->height for SVG files.
protected
getSvgDimensions() : void
See https://www.w3.org/TR/SVG11/coords.html#IntrinsicSizing
mimeTypeToImageType()
Gets the IMAGETYPE_* constant corresponding to the passed MIME type.
protected
static mimeTypeToImageType(string $mime_type) : int
This doesn't work for all cases, but it does for the most common ones.
Parameters
- $mime_type : string
Return values
int —An IMAGETYPE_* constant, or 0 if no match was found.
resizeUsingGD()
Resizes an image using the GD extension.
protected
resizeUsingGD(string $destination, int $max_width, int $max_height, int $preferred_type) : bool
Parameters
- $destination : string
-
The path to the destination image.
- $max_width : int
-
The maximum allowed width.
- $max_height : int
-
The maximum allowed height.
- $preferred_type : int
-
And IMAGETYPE_* constant.
Return values
bool —Whether the operation was successful.
resizeUsingImagick()
Resizes an image using the imagick extension.
protected
resizeUsingImagick(string $destination, int $max_width, int $max_height, int $preferred_type) : bool
Parameters
- $destination : string
-
The path to the destination image.
- $max_width : int
-
The maximum allowed width.
- $max_height : int
-
The maximum allowed height.
- $preferred_type : int
-
And IMAGETYPE_* constant.
Return values
bool —Whether the operation was successful.