Documentation

Image
in package

SMF

Uses BackwardCompatibility

Represents an image and allows low-level graphics operations to be performed, specially as needed for avatars, attachments, etc.

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
$backcompat : array<string|int, mixed>

Methods

__construct() : mixed: Constructor.
check() : bool: Searches through the file to see if there's potentially harmful content.
checkImageContents() : bool: Backward compatibility wrapper for the check() method.
checkMemory() : bool: Check whether we have enough memory to make a thumbnail.
checkSvgContents() : bool: Another backward compatibility wrapper for the check() method.
createThumbnail() : object|bool: Create a thumbnail of the given source file.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
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.
getSvgSize() : array<string|int, mixed>: Gets the dimensions of an SVG image (specifically, of its viewport).
gifOutputAsPng() : bool: Writes a GIF file to disk as a PNG file.
makeThumbnail() : bool: Backward compatibility wrapper for the createThumbnail() method.
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.
reencodeImage() : bool: Backward compatibility wrapper for the reencode() method.
resize() : bool: Resizes an image from a remote location or a local file.
resizeImage() : bool: Another backward compatibility wrapper for the resize() method.
resizeImageFile() : bool: Backward compatibility wrapper for the resize() method.
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 extesion.
resizeUsingImagick() : bool: Resizes an image using the imagick extesion.

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']

$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.

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['func_names' => ['getImageTypes' => 'getImageTypes', 'getSupportedFormats' => 'getSupportedFormats', 'checkMemory' => 'imageMemoryCheck', 'getSizeExternal' => 'url_image_size', 'gifOutputAsPng' => 'gif_outputAsPng', 'getSvgSize' => 'getSvgSize', 'makeThumbnail' => 'createThumbnail', 'reencodeImage' => 'reencodeImage', 'checkImageContents' => 'checkImageContents', 'checkSvgContents' => 'checkSvgContents', 'resizeImageFile' => 'resizeImageFile', 'resizeImage' => 'resizeImage']]

BackwardCompatibility settings for this class.

__construct()

Constructor.


    public
                    __construct( $source[,  $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 :: Either the path or URL of an image, or raw image data.
$strict : = 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.

checkImageContents()

Backward compatibility wrapper for the check() method.


    public
            static        checkImageContents(string $source[, bool $extensive = false ]) : bool

Parameters

$source : string: The path to the source image.
$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.

checkSvgContents()

Another backward compatibility wrapper for the check() method.


    public
            static        checkSvgContents(string $source) : bool

Parameters

$source : string: The path to the source image.

Return values

bool —

Whether the image appears to be safe.

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.

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.


    public
            static        exportStatic() : void

To do so:

Use this trait in the class.
At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names']. Likewise, a class's static methods are not exported as global functions unless explicitly included in $backcompat['func_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

$backcompat['func_names'] is a simple array where the keys are the names of one or more of a class's static methods, and the values are the names that should be used for global functions that will encapsulate those methods. Methods that are not named in this array will not be exported.

Adding non-static properties or methods to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

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.

getSvgSize()

Gets the dimensions of an SVG image (specifically, of its viewport).


    public
            static        getSvgSize(string $filepath) : array<string|int, mixed>

If $filepath is not the path to a valid SVG file, the returned width and height will both be null.

See https://www.w3.org/TR/SVG11/coords.html#IntrinsicSizing

This method only exists for backward compatibility purposes. New code should just create a new instance of this class for the SVG and then get its width and height properties directly.

Parameters

$filepath : string: The path to the SVG file.

Return values

array<string|int, mixed> —

The width and height of the SVG image in pixels.

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.

makeThumbnail()

Backward compatibility wrapper for the createThumbnail() method.


    public
            static        makeThumbnail(string $source, int $max_width, int $max_height) : bool

Parameters

$source : string: The path to the source image.
$max_width : int: The maximum allowed width.
$max_height : int: The maximum allowed height.

Return values

bool —

Whether the thumbnail creation 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.

reencodeImage()

Backward compatibility wrapper for the reencode() method.


    public
            static        reencodeImage(string $source[, int $preferred_type = 0 ]) : bool

Parameters

$source : string: The path to the source image.
$preferred_type : int = 0: And IMAGETYPE_* constant, or 0 for automatic.

Return values

bool —

Whether the 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.

resizeImage()

Another backward compatibility wrapper for the resize() method.


    public
            static        resizeImage(string $source, string $destination, int $src_width, int $src_height, int $max_width, int $max_height[, int $preferred_type = 0 ]) : bool

Parameters

$source : string: The source image data as a string.
$destination : string: The path to the destination image.
$src_width : int: The width of the source image. (Ignored.)
$src_height : int: The height of the source image. (Ignored.)
$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 the operation was successful.

resizeImageFile()

Backward compatibility wrapper for the resize() method.


    public
            static        resizeImageFile(string $source, string $destination, int $max_width, int $max_height[, int $preferred_type = 0 ]) : bool

Parameters

$source : string: The path to the source image.
$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 the operation was successful.

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 extesion.


    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 extesion.


    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.

Image in package SMF Uses BackwardCompatibility

Table of Contents

Constants

Properties

Methods

Constants

DEFAULT_IMAGETYPE

IMAGETYPE_TO_IMAGICK

Properties

$embedded_thumb

$filesize

$height

$image_types

$is_temp

$mime_type

$orientation

$original

$pathinfo

$source

$supported

$type

$width

$force_resize

$backcompat

Methods

__construct()

Parameters

check()

Parameters

Return values

checkImageContents()

Parameters

Return values

checkMemory()

Parameters

Return values

checkSvgContents()

Parameters

Return values

createThumbnail()

Parameters

Return values

exportStatic()

getImageTypes()

Return values

getSizeExternal()

Parameters

Return values

getSupportedFormats()

Return values

getSvgSize()

Parameters

Return values

gifOutputAsPng()

Parameters

Return values

makeThumbnail()

Parameters

Return values

move()

Parameters

Return values

reencode()

Parameters

Return values

reencodeImage()

Parameters

Return values

resize()

Parameters

Return values

resizeImage()

Parameters

Return values

resizeImageFile()

Parameters

Return values

shouldResize()

Parameters

Return values

Image
in package

SMF

Uses BackwardCompatibility