final class \SmartImageGdProcess
{ } ->

Class: Smart Image GD Process - provide a class for GD image processing for:
Safe Filter, Convert Format, Resize (Resample), Apply Watermark for a GIF / PNG / JPG / WEBP image.
For Safe Filter / Convert Format just construct this class and then ->getImageData().
For Resize (Resample) an image use ->resizeImage().
For Apply an image watermark over an image use: ->applyWatermark()

Language: PHP
Located at: lib/framework/plugins/lib_imgd.php
Package: Plugins:Image
Namespace: \
Class Name: SmartImageGdProcess
Version: v.20221223
Depends: PHP GD extension with support for: imagecreatetruecolor / imagecreatefromstring / getimagesizefromstring ; classes: Smart, SmartFileSysUtils
Usage: dynamic object: (new Class())->method() - This class provides only DYNAMIC methods

class Methods

public function __construct ( $imgdata, STRING $imginfo = "" ) {} @

@param: {MIXED} $imgstr: the image data STRING of an image: GIF / PNG / JPG / WEBP ; or the ARRAY definition for a new image [ 'width' => 200, 'height' => 100, 'bgcolor' => [0..255, 0..255, 0..255] ]
@param: {STRING} $imginfo: *Optional* an identifier of the image (Ex: the image name, used for error log or debug messages)

Class constructor

public function __destruct ( ) {} @

Class destructor

public function setDebug ( BOOL $debug ) {} ->

@param: {BOOL} $debug: if TRUE set Debug ON else set Debug OFF ; By default Debug is OFF

Set Debug ON / OFF

public function getStatusOk ( ) {} -> BOOL

@return: {BOOL} TRUE if OK / FALSE if NOT OK

Get the OK status of the image processing

public function getLastMessage ( ) {} -> STRING

@return: {STRING} the message if any or empty string

Get last error / warning message

public function getImageWidth ( ) {} -> INTEGER

@return: {INTEGER} image width in pixels or -1 on error

Get the Width of the Image (recalculated after each processing)
By default (if no processing) returns the original width of the input image
On error will return -1

public function getImageHeight ( ) {} -> INTEGER

@return: {INTEGER} image width in pixels or -1 on error

Get the Height of the Image (recalculated after each processing)
By default (if no processing) returns the original width of the input image
On error will return -1

public function getImageType ( ) {} -> ENUM

@return: {ENUM} '' | 'gif' | 'png' | 'jpg' | 'webp'

Get the detected Image type of the original image data
This will be preserved and never changed upon different image processings
On error will return empty string ''
Possible errors when detecting an image type:
- corrupted or invalid image data
- invalid type: only GIF / PNG / JPG / WEBP types are supported
- image size is very high: images over 8 Megapixels may fail !

public function getImageData ( ENUM $type = "", INTEGER+ $quality = 100, INTEGER+ $compression = 6, MIXED $filters = "" ) {} -> STRING

@return: {STRING} '' on error or image data in the specified format: GIF / PNG / JPG / WEBP
@param: {ENUM} $type: *Optional* '' | 'gif' | 'png' | 'jpg' | 'webp' ; if '' will return the exact type as the input image
@param: {INTEGER+} $quality: *Optional* 1..100 ; Default is 100 ; The quality of the image ; currently applies just for JPG and WEBP
@param: {INTEGER+} $compression: *Optonal* 0..9 ; Default is 6 ; The image compression level (zlib) ; currently applies just for PNG
@param: {MIXED} $filters: *Optional* ; Default is '' = no filters ; false = PNG_NO_FILTER ; true = PNG_ALL_FILTERS ; array(PNG_FILTER_SUB, PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, PNG_FILTER_NONE) = array with filters ; currently applies just for PNG (using array of filters depends on what filters are available in LibPNG)

Get GD image data as: GIF / PNG / JPG / WEBP

public function resizeImage ( INTEGER+ $resize_width, INTEGER+ $resize_height, BOOLEAN $crop = 0, ENUM $mode = 0, ARRAY $bg_color_rgb = [0 => 0, 1 => 0, 2 => 0] ) {} -> BOOLEAN

@hints: Create a Preview: w>0, h>0, crop=true/false, mode=0 ; Create a (classic) image resize: w>=0, h>=0, crop=false, mode=2/1
@return: {BOOLEAN} TRUE on success ; FALSE on error / fail
@param: {INTEGER+} $resize_width: The width of the resized image: 16..1920 ; can be zero only when $resize_height > 0 ; if zero, will become relative and calculated by aspect ratio based on resize height
@param: {INTEGER+} $resize_height: The height of the resized image: 16..1920 ; can be zero only when $resize_width > 0 ; if zero, will become relative and calculated by aspect ratio based on resize width
@param: {BOOLEAN} $crop: *Optional* ; Default is 0 ; If 0 will do a normal resize (aspect fit) ; If > 0 will crop the resampled image (aspect fill) as 1=top-left ; 2=top-center ; 3=center-center
@param: {ENUM} $mode: *Optional* 0 | 1 | 2 ; Default is 0 = absolute resample ; 1 = absolute resample + preserve dimensions if lower ; 2 = preserve if lower + relative dimensions ; 3 = relative dimensions
@param: {ARRAY} $bg_color_rgb: The RGB color as Array [0..255, 0..255, 0..255]

Resize (Resample) +/- Crop an image: GIF / PNG / JPG / WEBP

public function applyWatermark ( STRING $wtistr, ENUM $gravity, INTEGER $offsx = 0, INTEGER $offsy = 0 ) {} -> BOOLEAN

@hints: the image transparency of the watermark will be preserved ; so if a watermark with transparency is required, use a watermark with embedded transparency
@return: {BOOLEAN} TRUE on success ; FALSE on error / fail
@param: {STRING} $wtistr: the image data string of the watermark image: GIF / PNG / JPG / WEBP
@param: {ENUM} $gravity: the placement of the watermark on image: c/center, n/north, s/south, w/west, e/east, nw/northwest, ne/northeast, sw/southwest, se/southeast
@param: {INTEGER} $offsx: correction offset X for watermark placement
@param: {INTEGER} $offsy: correction offset Y for watermark placement

Apply an image Watermark (GIF / PNG / JPG / WEBP) on an image: GIF / PNG / JPG / WEBP

public function calculateTextBBox ( STRING $text, INTEGER $angle, INTEGER $size, ENUM $font = "lib/core/plugins/fonts/typo/sans/ibm-plex-sans-regular.ttf" ) {} -> ARRAY

@hints: this works just with TTF fonts
@return: {ARRAY} return an empty array on error / on success returns an array with 8 coordinates as [ 0: lower left corner, X position ; 1: lower left corner, Y position ; 2: lower right corner, X position ; 3: lower right corner, Y position ; 4: upper right corner, X position ; 5: upper right corner, Y position ; 6: upper left corner, X position ; 7: upper left corner, Y position ]
@param: {STRING} $text: the text to be applied
@param: {INTEGER} $angle: TTF angle rotation (0..180) degrees
@param: {INTEGER} $size: TTF font size
@param: {ENUM} $font: *Optional* The font to be used: character's font (1..5 for built-in gd font ; path/to/font.gdf ; path/to/font.ttf) ; Default is: lib/core/plugins/fonts/typo/sans/ibm-plex-sans-regular.ttf

Calculate TTF text bounding box for an image

public function prepareTextLines ( STRING $text, INTEGER $angle, INTEGER $size, INTEGER $width, INTEGER $margin, ENUM $font ) {} -> ARRAY

@hints: this works just with TTF fonts ; the text transparency is made by the $color_rgb alpha channel
@return: {ARRAY} Array of Text split into lines [0..n]
@param: {STRING} $text: the text to be applied
@param: {INTEGER} $angle: TTF angle rotation (0..180) degrees
@param: {INTEGER} $size: TTF font size
@param: {INTEGER} $width: width of text area (includding margins)
@param: {INTEGER} $margin: left margin for text placement ; Default is 0
@param: {ENUM} $font: The font to be used: character's font (1..5 for built-in gd font ; path/to/font.gdf ; path/to/font.ttf) ; Default is: lib/core/plugins/fonts/typo/sans/ibm-plex-sans-regular.ttf

Prepare multi-line text by width and margin (text will be wrapped on multiple lines) on an image

public function applyWrapText ( STRING $text, ENUM $align = "left", INTEGER $margin = 0, INTEGER $top = 0, INTEGER $vlinespace = 5, INTEGER $angle = 0, INTEGER $size = 10, ENUM $font = "lib/core/plugins/fonts/typo/sans/ibm-plex-sans-regular.ttf", ARRAY $color_rgb = [0 => 0, 1 => 0, 2 => 0, 3 => 0] ) {} -> BOOLEAN

@hints: this works just with TTF fonts ; the text transparency is made by the $color_rgb alpha channel
@return: {BOOLEAN} TRUE on success ; FALSE on error / fail
@param: {STRING} $text: the text to be applied
@param: {ENUM} $align: *Optional* the align mode: left | center | right ; default is left
@param: {INTEGER} $margin: *Optional* left margin for text placement ; Default is 0
@param: {INTEGER} $top: *Optional* top margin for text placement ; Default is 0
@param: {INTEGER} $vlinespace: *Optional* vertical line spacing (space between vertical text lines)
@param: {INTEGER} $angle: *Optional* TTF angle rotation (0..180) degrees ; Default is 0 ; Applies just for Align=left ; for Align=center / Align=right ... to be done in the future ...
@param: {INTEGER} $size: *Optional* TTF font size ; Default is 10 | null (for built-in or GDF fonts)
@param: {ENUM} $font: *Optional* The font to be used: character's font (1..5 for built-in gd font ; path/to/font.gdf ; path/to/font.ttf) ; Default is: lib/core/plugins/fonts/typo/sans/ibm-plex-sans-regular.ttf
@param: {ARRAY} $color_rgb: *Optional* The RGB color with optional alpha channel as Array [0..255, 0..255, 0..255, 0..127] ; Default is: [0, 0, 0, 0]

Apply multi-line text (text will be wrapped on multiple lines) on an image: GIF / PNG / JPG / WEBP

public function applyText ( STRING $text, INTEGER $offsx = 0, INTEGER $offsy = 0, INTEGER $angle = 0, INTEGER $size = 10, ENUM $font = "lib/core/plugins/fonts/typo/sans/ibm-plex-sans-regular.ttf", ARRAY $color_rgb = [0 => 0, 1 => 0, 2 => 0, 3 => 0] ) {} -> BOOLEAN

@hints: the text transparency is made by the $color_rgb alpha channel
@return: {BOOLEAN} TRUE on success ; FALSE on error / fail
@param: {STRING} $text: the text to be applied
@param: {INTEGER} $offsx: *Optional* correction offset X for text placement ; Default is 0
@param: {INTEGER} $offsy: *Optional* correction offset Y for text placement ; Default is 0
@param: {INTEGER} $angle: *Optional* TTF angle rotation (0..180) degrees ; Default is 0 | null (for built-in or GDF fonts)
@param: {INTEGER} $size: *Optional* TTF font size ; Default is 10 | null (for built-in or GDF fonts)
@param: {ENUM} $font: *Optional* The font to be used: character's font (1..5 for built-in gd font ; path/to/font.gdf ; path/to/font.ttf) ; Default is: lib/core/plugins/fonts/typo/sans/ibm-plex-sans-regular.ttf
@param: {ARRAY} $color_rgb: *Optional* The RGB color with optional alpha channel as Array [0..255, 0..255, 0..255, 0..127] ; Default is: [0, 0, 0, 0]

Apply text on an image: GIF / PNG / JPG / WEBP

class Properties

class Constants

Sample code: PHP


<?php

$imgd = new SmartImageGdProcess(
    (string) file_get_contents('img/sample-2.jpg')
 );

 $resize = $imgd->resizeImage(160, 160, true, 0); // create preview (with crop)
 //$resize = $imgd->resizeImage(1280, 1280, false, 2); // create resample with: preserve if lower + relative dimensions
 if(!$resize) {
    throw new Exception('R! '.(string)$imgd->getLastMessage());
 } //end if

 $wtistr = file_get_contents('img/watermark.gif');
 $watermark = $imgd->applyWatermark($wtistr, 'c', 0, 0);
 if(!$watermark) {
     throw new Exception('W! '.(string)$imgd->getLastMessage());
 } //end if

 $png = '';
 if($imgd->getStatusOk() === true) {
     $png = (string) $imgd->getImageData('png', 100, 9);
 } //end if
 if((string)$png == '') {
     throw new Exception('S! '.(string)$imgd->getLastMessage());
 } //end if

 header('Content-Type: image/png');
 header('Content-Disposition: inline; filename="sample-image-'.time().'.png"');
 echo $png;

// #end php code

documentation generated on: 2023-10-19 23:15:48 +0000

final class \SmartImageGdProcess { } ->

class Methods

class Properties

class Constants

Sample code: PHP

final class \SmartImageGdProcess
{ } ->