vBulletin 5.6.5 API

vB_Image_GD extends vB_Image
in package

Image class for GD Image Library

Tags
version

$Revision: 102901 $

date

$Date: 2019-09-23 19:29:15 -0700 (Mon, 23 Sep 2019) $

Table of Contents

ALLOW_RANDOM_COLOR  = 8
ALLOW_RANDOM_FONT  = 1
These make up the bit field to enable specific parts of image verification
ALLOW_RANDOM_SHAPE  = 16
ALLOW_RANDOM_SIZE  = 2
ALLOW_RANDOM_SLANT  = 4
GIF  = 1
Global image type defines used by serveral functions
JPG  = 2
PNG  = 3
$extension_map  : array<string|int, mixed>
$imageinfo  : mixed
$imagetype_constants  : array<string|int, mixed>
Used to translate from imagetype constants to extension name.
$info_extensions  : array<string|int, mixed>
$invalid  : mixed
$must_convert_types  : array<string|int, mixed>
$options  : array<string|int, mixed>
Options from datastore
$regimageoption  : array<string|int, mixed>
$resize_types  : array<string|int, mixed>
$thumb_extensions  : array<string|int, mixed>
$type_to_canonical_extension  : mixed
It's not very clear if $extension_map was supposed to be mimetype => extension, or extension => "type".
$imagefilelocation  : mixed
$preserveExif  : mixed
$thumbcolor  : string
__construct()  : void
Constructor. Sets up resizable types, extensions, etc.
__destruct()  : mixed
__serialize()  : mixed
__sleep()  : mixed
__unserialize()  : mixed
__wakeup()  : mixed
bestResize()  : mixed
Attempt to resize file if the filesize is too large after an initial resize to max dimensions or the file is already within max dimensions but the filesize is too large
canThumbnailPdf()  : bool
Returns true if it can detect that the required libraries for supporting jpg thumbnails for PDFs are installed and available.
compareExtensionToFilesignature()  : mixed
cropImg()  : mixed
Crop the profile image
fetchImageExtensions()  : mixed
fetchImageInfo()  : array<string|int, mixed>
See function definition in vB_Image
fetchImageInfoForThumbnails()  : mixed
fetchImagetypeFromExtension()  : bool
Checks if supplied extension can be used by fetchThumbnail
fetchMustConvert()  : bool
fetchThumbnail()  : array<string|int, mixed>
Returns an array containing a thumbnail, creation time, thumbnail size and any errors
fileContentIsAnimatedGif()  : mixed
fileIsAnimatedGif()  : mixed
fileLocationIsImage()  : bool
Determine if the given location holds a whitelisted image file. Return false if not an image or not whitelisted.
getConvertTypes()  : mixed
standard getter
getExtensionFromFileheaders()  : mixed
getExtensionMap()  : mixed
standard getter
getImageFromString()  : array<string|int, mixed>
See function definition in vB_Image
getInfoExtensions()  : mixed
standard getter
getOrientation()  : mixed
getResizeTypes()  : mixed
standard getter
getThumbExtensions()  : mixed
standard getter
imageThumbnailSupported()  : bool
Determine if the given extension can have an image thumbnail. Basically an alias for isValidThumbnailExtension().
instance()  : object
Select image library
isImageExtension()  : bool
Determine if the given extension should be treated as an image for size $type as far as HTML is concerned. These types also align with the cangetimgattachment permission.
isValidInfoExtension()  : bool
Checks if supplied extension can be used by fetchImageInfo
isValidResizeType()  : bool
Checks if supplied extension can be resized into a smaller permanent image, not to be used for PSD, PDF, etc as it will lose the original format
isValidThumbnailExtension()  : bool
Checks if supplied extension can be used by fetchThumbnail
loadFileData()  : mixed
loadImage()  : mixed
CALLER MUST CLEAN UP/REMOVE OLD FILE. This is to prevent the image class from removing unknown files that it didn't create.
unloadImage()  : mixed
verifyFileHeadersAndExif()  : bool
Checks for HTML tags that can be exploited via IE, & scripts in exif tags
verifyImageFile()  : bool
Checks for HTML tags that can be exploited via IE, scripts in exif tags, and checks file signature against a whitelist of image signatures (currently only support gif, jpg, bmp, tif, psd)
annotategd()  : string
Return a letter position command
annotatettf()  : string
Return a letter position command
blur()  : image
Apply a blur filter to an image
checkExif()  : mixed
fetchImageResource()  : resource
Create blank image
fetchRegimageBackgrounds()  : array<string|int, mixed>
Fetches image files from the backgrounds directory
fetchRegimageFonts()  : array<string|int, mixed>
Fetches True Type fonts from the fonts directory
flipimage()  : object
mirror an image horizontally. Can be extended to other flips but this is all we need for now
forceRewriteImage()  : mixed
is_animated_gif()  : mixed
magicWhiteList()  : mixed
orientationToAnglesCW()  : mixed
orientationToFlipFlop()  : mixed
orientImageInternalGD()  : mixed
Rotate/flip/flop image from $fileContents as specified by 'orientation' exif tag. Caller must perform file-write using the image resource.
printImage()  : void
Output an image
skipWriteImage()  : mixed
swirl()  : object
Apply a swirl/twirl filter to an image
unsharpmask()  : void
Sharpen an image
wave()  : image
Apply a wave filter to an image
fetchResizedImageFromFiledata()  : mixed
Fetch a resize image from an existing filedata
getImage()  : mixed
getUnsafeImageInfo()  : mixed

Constants

ALLOW_RANDOM_COLOR

public mixed ALLOW_RANDOM_COLOR = 8

ALLOW_RANDOM_FONT

These make up the bit field to enable specific parts of image verification

public mixed ALLOW_RANDOM_FONT = 1

ALLOW_RANDOM_SHAPE

public mixed ALLOW_RANDOM_SHAPE = 16

ALLOW_RANDOM_SIZE

public mixed ALLOW_RANDOM_SIZE = 2

ALLOW_RANDOM_SLANT

public mixed ALLOW_RANDOM_SLANT = 4

GIF

Global image type defines used by serveral functions

public mixed GIF = 1

Properties

$extension_map

public array<string|int, mixed> $extension_map = array('gif' => 'GIF', 'jpg' => 'JPEG', 'jpeg' => 'JPEG', 'jpe' => 'JPEG', 'png' => 'PNG', 'bmp' => 'BMP', 'tif' => 'TIFF', 'tiff' => 'TIFF', 'psd' => 'PSD', 'pdf' => 'PDF')

$imageinfo

public mixed $imageinfo = ull

$imagetype_constants

Used to translate from imagetype constants to extension name.

public array<string|int, mixed> $imagetype_constants = array(1 => 'GIF', 2 => 'JPEG', 3 => 'PNG', 5 => 'PSD', 6 => 'BMP', 7 => 'TIFF', 8 => 'TIFF')

$info_extensions

public array<string|int, mixed> $info_extensions = array()

$invalid

public mixed $invalid = alse

$must_convert_types

public array<string|int, mixed> $must_convert_types = array()

$options

Options from datastore

public array<string|int, mixed> $options = ull

$regimageoption

public array<string|int, mixed> $regimageoption = array('randomfont' => alse, 'randomsize' => alse, 'randomslant' => alse, 'randomcolor' => alse, 'randomshape' => alse)

$resize_types

public array<string|int, mixed> $resize_types = array()

$thumb_extensions

public array<string|int, mixed> $thumb_extensions = array()

$type_to_canonical_extension

It's not very clear if $extension_map was supposed to be mimetype => extension, or extension => "type".

public mixed $type_to_canonical_extension = array( 'GIF' => 'gif', 'JPEG' => 'jpg', // apparently .jpg is more common than .jpeg 'PNG' => 'png', 'BMP' => 'bmp', 'TIFF' => 'tiff', 'PSD' => 'psd', 'PDF' => 'pdf', )

It's currently used for both, which doesn't make a lot of sense, so I'm adding the following to make $extension_map into extension => "type", then "type" to "canonical extension" with below

$imagefilelocation

protected mixed $imagefilelocation = ull

$preserveExif

protected mixed $preserveExif = alse

$thumbcolor

protected string $thumbcolor = array('r' => 0, 'b' => 0, 'g' => 0)

Methods

__construct()

Constructor. Sets up resizable types, extensions, etc.

public __construct(mixed $options[, mixed $extras = array() ]) : void
Parameters
$options : mixed
$extras : mixed = array()
Return values
void

__destruct()

public final __destruct() : mixed
Return values
mixed

__serialize()

public __serialize() : mixed
Return values
mixed

__sleep()

public __sleep() : mixed
Return values
mixed

__unserialize()

public __unserialize(mixed $serialized) : mixed
Parameters
$serialized : mixed
Return values
mixed

__wakeup()

public __wakeup() : mixed
Return values
mixed

bestResize()

Attempt to resize file if the filesize is too large after an initial resize to max dimensions or the file is already within max dimensions but the filesize is too large

public bestResize(mixed $width, mixed $height) : mixed
Parameters
$width : mixed
$height : mixed
Return values
mixed

canThumbnailPdf()

Returns true if it can detect that the required libraries for supporting jpg thumbnails for PDFs are installed and available.

public canThumbnailPdf() : bool

Currently used by upgrade scripts & setting validation code to check if GhostScript is installed and configured in the delegates file when using the ImageMagick library, or attempt a sample PDF conversion when using the Imagick library. Do not add this check as part of init/startup, as it can be slow. It should only be called infrequently as required!

Return values
bool

compareExtensionToFilesignature()

public final compareExtensionToFilesignature(mixed $extension, mixed $location) : mixed
Parameters
$extension : mixed
$location : mixed
Return values
mixed

cropImg()

Crop the profile image

public cropImg(mixed $imgInfo[, mixed $maxwidth = 100 ][, mixed $maxheight = 100 ][, mixed $forceResize = false ]) : mixed
@param 	array $imgInfo contains all the required information
  • filename
  • extension
  • filedata
  • width
  • height
  • x1
  • y1
Parameters
$imgInfo : mixed
$maxwidth : mixed = 100

@param int $maxheight @param bool $forceResize force generation of a new file

$maxheight : mixed = 100
$forceResize : mixed = false
Return values
mixed

array of data with the cropped image info:

  • width
  • height
  • filedata
  • filesize
  • dateline
  • imageerror (not used)
  • filename (not used)

fetchImageExtensions()

public final fetchImageExtensions() : mixed
Return values
mixed

fetchImageInfo()

See function definition in vB_Image

public fetchImageInfo(mixed $filename) : array<string|int, mixed>
Parameters
$filename : mixed
Return values
array<string|int, mixed>

[0] int width [1] int height [2] string type ('GIF', 'JPEG', 'PNG', 'PSD', 'BMP', 'TIFF',) (and so on) [scenes] int scenes [channels] int (DEPRECATED) Number of channels [bits] int Number of bits per pixel [library] string Library Identifier

fetchImageInfoForThumbnails()

public fetchImageInfoForThumbnails(mixed $filename) : mixed
Parameters
$filename : mixed
Return values
mixed

fetchImagetypeFromExtension()

Checks if supplied extension can be used by fetchThumbnail

public final fetchImagetypeFromExtension(string $extension) : bool
Parameters
$extension : string

Extension of file

Return values
bool

fetchMustConvert()

public final fetchMustConvert(string $type) : bool
Parameters
$type : string

Type of image from $info_extensions

Return values
bool

fetchThumbnail()

Returns an array containing a thumbnail, creation time, thumbnail size and any errors

public fetchThumbnail(mixed $filename, mixed $location[, mixed $maxwidth = 100 ][, mixed $maxheight = 100 ][, mixed $quality = 75 ][, mixed $labelimage = false ][, mixed $drawborder = false ][, mixed $jpegconvert = false ][, mixed $sharpen = true ][, mixed $owidth = null ][, mixed $oheight = null ][, mixed $ofilesize = null ]) : array<string|int, mixed>
Parameters
$filename : mixed
$location : mixed
$maxwidth : mixed = 100
$maxheight : mixed = 100
$quality : mixed = 75
$labelimage : mixed = false
$drawborder : mixed = false
$jpegconvert : mixed = false
$sharpen : mixed = true
$owidth : mixed = null
$oheight : mixed = null
$ofilesize : mixed = null
Tags
see
vB_Image::fetchThumbnail()
Return values
array<string|int, mixed>

fileContentIsAnimatedGif()

public final fileContentIsAnimatedGif(mixed $filecontent) : mixed
Parameters
$filecontent : mixed
Return values
mixed

fileIsAnimatedGif()

public final fileIsAnimatedGif(mixed $filename) : mixed
Parameters
$filename : mixed
Return values
mixed

fileLocationIsImage()

Determine if the given location holds a whitelisted image file. Return false if not an image or not whitelisted.

public final fileLocationIsImage(string $location) : bool
Parameters
$location : string

Full file path

Return values
bool

getConvertTypes()

standard getter

public final getConvertTypes() : mixed
Return values
mixed

array of must conver types

getExtensionFromFileheaders()

public final getExtensionFromFileheaders(mixed $location) : mixed
Parameters
$location : mixed
Return values
mixed

getExtensionMap()

standard getter

public getExtensionMap() : mixed
Return values
mixed

array of file extension-to-type maps , like 'gif' => "GIF' *

getImageFromString()

See function definition in vB_Image

public getImageFromString(mixed $string[, mixed $moveabout = true ]) : array<string|int, mixed>
Parameters
$string : mixed
$moveabout : mixed = true
Return values
array<string|int, mixed>

Array containing imageInfo: filedata, filesize, filetype and htmltype

getInfoExtensions()

standard getter

public final getInfoExtensions() : mixed
Return values
mixed

array of valid extensions

getOrientation()

public final getOrientation(mixed $location) : mixed
Parameters
$location : mixed
Return values
mixed

getResizeTypes()

standard getter

public final getResizeTypes() : mixed
Return values
mixed

array of resize types

getThumbExtensions()

standard getter

public final getThumbExtensions() : mixed
Return values
mixed

array of thumbnail ext

imageThumbnailSupported()

Determine if the given extension can have an image thumbnail. Basically an alias for isValidThumbnailExtension().

public final imageThumbnailSupported(string $extension) : bool

Mostly for the PDF to image thumbnail handling for imagemagick.

Parameters
$extension : string

File extension, usually from filedata.extension.

Return values
bool

instance()

Select image library

public static instance([mixed $type = 'image' ][, mixed $additionalOptions = array() ]) : object
Parameters
$type : mixed = 'image'
$additionalOptions : mixed = array()
Return values
object

isImageExtension()

Determine if the given extension should be treated as an image for size $type as far as HTML is concerned. These types also align with the cangetimgattachment permission.

public final isImageExtension(string $extension[, string $type = vB_Api_Filedata::SIZE_FULL ]) : bool
Parameters
$extension : string

File extension, usually from filedata.extension.

$type : string = vB_Api_Filedata::SIZE_FULL

One of vB_Api_Filedata::SIZE_X strings

Return values
bool

isValidInfoExtension()

Checks if supplied extension can be used by fetchImageInfo

public final isValidInfoExtension(string $extension) : bool
Parameters
$extension : string

Extension of file

Return values
bool

isValidResizeType()

Checks if supplied extension can be resized into a smaller permanent image, not to be used for PSD, PDF, etc as it will lose the original format

public final isValidResizeType(string $type) : bool
Parameters
$type : string

Type of image from $info_extensions

Return values
bool

isValidThumbnailExtension()

Checks if supplied extension can be used by fetchThumbnail

public final isValidThumbnailExtension(string $extension) : bool
Parameters
$extension : string

Extension of file

Return values
bool

loadFileData()

public loadFileData(mixed $record[, mixed $type = vB_Api_Filedata::SIZE_FULL ][, mixed $includeData = true ]) : mixed
Parameters
$record : mixed
$type : mixed = vB_Api_Filedata::SIZE_FULL
$includeData : mixed = true
Return values
mixed

loadImage()

CALLER MUST CLEAN UP/REMOVE OLD FILE. This is to prevent the image class from removing unknown files that it didn't create.

public final loadImage(mixed $location) : mixed
Parameters
$location : mixed
Return values
mixed

unloadImage()

public final unloadImage() : mixed
Return values
mixed

verifyFileHeadersAndExif()

Checks for HTML tags that can be exploited via IE, & scripts in exif tags

public verifyFileHeadersAndExif(string $fileContents, string $location) : bool
Parameters
$fileContents : string

Contents of the file e.g. file_get_contents($location)

$location : string

Full filepah

Return values
bool

verifyImageFile()

Checks for HTML tags that can be exploited via IE, scripts in exif tags, and checks file signature against a whitelist of image signatures (currently only support gif, jpg, bmp, tif, psd)

public verifyImageFile(string $fileContents, string $location) : bool
Parameters
$fileContents : string

Contents of the file e.g. file_get_contents($location)

$location : string

Full filepah

Return values
bool

True if nothing was detected, false if headers were not found, throws an exception if possible nasty was detected.

annotategd()

Return a letter position command

protected annotategd(mixed $image, mixed $letter[, mixed $random = true ]) : string
Parameters
$image : mixed
$letter : mixed
$random : mixed = true
Return values
string

annotatettf()

Return a letter position command

protected annotatettf(mixed $image, mixed $letter, mixed $font[, mixed $random = true ]) : string
Parameters
$image : mixed
$letter : mixed
$font : mixed
$random : mixed = true
Return values
string

blur()

Apply a blur filter to an image

protected blur(mixed &$image[, mixed $radius = 0.5 ]) : image
Parameters
$image : mixed
$radius : mixed = 0.5
Return values
image

checkExif()

protected checkExif(mixed $value, mixed $key) : mixed
Parameters
$value : mixed
$key : mixed
Return values
mixed

fetchImageResource()

Create blank image

protected fetchImageResource(mixed $width, mixed $height) : resource
Parameters
$width : mixed
$height : mixed
Return values
resource

fetchRegimageBackgrounds()

Fetches image files from the backgrounds directory

protected fetchRegimageBackgrounds() : array<string|int, mixed>
Return values
array<string|int, mixed>

fetchRegimageFonts()

Fetches True Type fonts from the fonts directory

protected fetchRegimageFonts() : array<string|int, mixed>
Return values
array<string|int, mixed>

flipimage()

mirror an image horizontally. Can be extended to other flips but this is all we need for now

protected flipimage(mixed &$image) : object
Parameters
$image : mixed
Return values
object

image

forceRewriteImage()

protected forceRewriteImage(mixed $fileContents, mixed $location) : mixed
Parameters
$fileContents : mixed
$location : mixed
Return values
mixed

is_animated_gif()

protected is_animated_gif(mixed $filename) : mixed
Parameters
$filename : mixed
Return values
mixed

magicWhiteList()

protected magicWhiteList(mixed $data[, mixed $return_extension = false ]) : mixed
Parameters
$data : mixed
$return_extension : mixed = false
Return values
mixed

orientationToAnglesCW()

protected orientationToAnglesCW(mixed $orientation) : mixed
Parameters
$orientation : mixed
Return values
mixed

orientationToFlipFlop()

protected orientationToFlipFlop(mixed $orientation) : mixed
Parameters
$orientation : mixed
Return values
mixed

orientImageInternalGD()

Rotate/flip/flop image from $fileContents as specified by 'orientation' exif tag. Caller must perform file-write using the image resource.

protected orientImageInternalGD(resource $image, int $orientation) : mixed
Parameters
$image : resource

GD Image resource from $this->getImage(). Return value of one of the imagecreatefrom_x() GD functions.

$orientation : int

image orientation from exif data, typically result of getOrientation($location)

Tags
access

protected

Return values
mixed

printImage()

Output an image

protected printImage(object &$image[, string $type = 'JPEG' ][, bool $headers = true ][, int $quality = 75 ][, string $filename = null ]) : void
Parameters
$image : object

Image file to convert. Will be destroyed!

$type : string = 'JPEG'

Output image type

$headers : bool = true

[DEPRECATED] Generate image header

$quality : int = 75

Jpeg Quality. Not used if $type != 'JPEG'

$filename : string = null

Optional. File write destination. If not provided, image stream will be output directly.

Return values
void

skipWriteImage()

protected skipWriteImage(mixed $fileContents, mixed $location) : mixed
Parameters
$fileContents : mixed
$location : mixed
Return values
mixed

swirl()

Apply a swirl/twirl filter to an image

protected swirl(mixed &$image[, mixed $degree = 0.005 ][, mixed $randirection = true ]) : object
Parameters
$image : mixed
$degree : mixed = 0.005
$randirection : mixed = true
Return values
object

image

unsharpmask()

Sharpen an image

protected unsharpmask(mixed &$finalimage[, mixed $amount = 50 ][, mixed $radius = 1 ], mixed $threshold) : void
Parameters
$finalimage : mixed
$amount : mixed = 50
$radius : mixed = 1
$threshold : mixed
Return values
void

wave()

Apply a wave filter to an image

protected wave(mixed &$image[, mixed $wave = 10 ][, mixed $randirection = true ]) : image
Parameters
$image : mixed
$wave : mixed = 10
$randirection : mixed = true
Return values
image

fetchResizedImageFromFiledata()

Fetch a resize image from an existing filedata

private fetchResizedImageFromFiledata(array<string|int, mixed> &$record, string $type) : mixed
Parameters
$record : array<string|int, mixed>

File information

$type : string

One of the vB_Api_Filedata type constants other than full (which should be handled without resizing). It does not accept a direct size value like the public functions. Use the vB_Api/Library sanitizeFiletype function to convert those to a valid type string.

Return values
mixed

getImage()

private getImage(mixed $location[, mixed $imageinfo = null ]) : mixed
Parameters
$location : mixed
$imageinfo : mixed = null
Return values
mixed

getUnsafeImageInfo()

private getUnsafeImageInfo(mixed $fileContents, mixed $filename) : mixed
Parameters
$fileContents : mixed
$filename : mixed
Return values
mixed

Search results