Flourish PHP Unframework

fImage

class, v1.0.0b33

Represents an image on the filesystem, also provides image manipulation functionality

Changes:
1.0.0b33Fixed a method signature 8/24/11
1.0.0b32Added a call to clearstatcache() to saveChanges() to solve a bug when fFile::output() is called in the same script execution 5/23/11
1.0.0b31Fixed a bug in using ImageMagick to convert files with a colon in the filename 3/20/11
1.0.0b30Added a check for systems using the GD extension and no memory limit, plus a check for ImageMagick's convert command failing 3/20/11
1.0.0b29Added checks for AIX 1/19/11
1.0.0b28Added the rotate() method, added code to try and prevent fatal errors due to hitting the memory limit when using GD 11/29/10
1.0.0b27Backwards Compatibility Break - changed the parameter order in crop() from $crop_from_x, $crop_from_y, $new_width, $new_height to $new_width, $new_height, $crop_from_x, $crop_from_y - added $horizontal_position and $vertical_position parameters to cropToRatio() 11/9/10
1.0.0b26Fixed a bug where processing via ImageMagick was not properly setting the default RGB colorspace 10/19/10
1.0.0b25Fixed the class to not generate multiple files when saving a JPG from an animated GIF or a TIF with a thumbnail 9/12/10
1.0.0b24Updated class to use fCore::startErrorCapture() instead of error_reporting() 8/9/10
1.0.0b23Fixed the class to detect when exec() is disabled and the function has a space before or after in the list 7/21/10
1.0.0b22Fixed isImageCompatible() to handle certain JPGs created with Photoshop 4/3/10
1.0.0b21Fixed resize() to allow dimensions to be numeric strings instead of just integers 4/9/10
1.0.0b20Added append() 3/15/10
1.0.0b19Updated for the new fFile API 3/5/10
1.0.0b18Fixed a bug in saveChanges() that would incorrectly cause new filenames to be created, added the $overwrite parameter to saveChanges(), added the $allow_upsizing parameter to resize() 3/3/10
1.0.0b17Fixed a couple of bug with using ImageMagick on Windows and BSD machines 3/2/10
1.0.0b16Fixed some bugs with GD not properly handling transparent backgrounds and desaturation of .gif files 10/27/09
1.0.0b15Added getDimensions() 8/7/09
1.0.0b14Performance updates for checking image type and compatiblity 7/31/09
1.0.0b13Updated class to work even if the file extension is wrong or not present, saveChanges() detects files that aren't writable 7/29/09
1.0.0b12Fixed a bug where calling saveChanges() after unserializing would throw an exception related to the image processor 5/27/09
1.0.0b11Added a crop() method 5/27/09
1.0.0b10Fixed a bug with GD not saving changes to files ending in .jpeg 3/18/09
1.0.0b9Changed processWithGD() to explicitly free the image resource 3/18/09
1.0.0b8Updated for new fCore API 2/16/09
1.0.0b7Changed @ error suppression operator to error_reporting() calls 1/26/09
1.0.0b6Fixed cropToRatio() and resize() to always return the object even if nothing is to be done 1/5/09
1.0.0b5Added check to see if exec() is disabled, which causes ImageMagick to not work 1/3/09
1.0.0b4Fixed saveChanges() to not delete the image if no changes have been made 12/18/08
1.0.0b3Fixed a bug with $jpeg_quality in saveChanges() from 1.0.0b2 12/16/08
1.0.0b2Changed some int casts to round() to fix resize() dimension issues 12/11/08
1.0.0bThe initial implementation 12/19/07

Genealogy

Class Tree

fFile
   |
   --fImage

Inherited Variables

fFile::$deleted
A backtrace from when the file was deleted
fFile::$file
The full path to the file

Inherited Methods

fFile::__construct()
Creates an object to represent a file on the filesystem
fFile::__clone()
Duplicates a file in the current directory when the object is cloned
fFile::__get()
All requests that hit this method should be requests for callbacks
fFile::__sleep()
The iterator information doesn't need to be serialized since a resource can't be
fFile::__toString()
Returns the filename of the file
fFile::__wakeup()
Re-inserts the file back into the filesystem map when unserialized
fFile::append()
Appends the provided data to the file
fFile::count()
Returns the number of lines in the file
fFile::create()
Creates a file on the filesystem and returns an object representing it.
fFile::current()
Returns the current line of the file (required by iterator interface)
fFile::delete()
Deletes the current file
fFile::determineMimeType()
Determines the file's mime type by either looking at the file contents or matching the extension
fFile::duplicate()
Creates a new file object with a copy of this file
fFile::getExtension()
Gets the file extension
fFile::getMimeType()
Gets the file's mime type
fFile::getMTime()
Returns the last modification time of the file
fFile::getName()
Gets the filename (i.e. does not include the directory)
fFile::getParent()
Gets the directory the file is located in
fFile::getPath()
Gets the file's current path (directory and filename)
fFile::getSize()
Gets the size of the file
fFile::isWritable()
Check to see if the current file is writable
fFile::key()
Returns the current one-based line number (required by iterator interface)
fFile::move()
Moves the current file to a different directory
fFile::next()
Advances to the next line in the file (required by iterator interface)
fFile::output()
Prints the contents of the file
fFile::read()
Reads the data from the file
fFile::rename()
Renames the current file
fFile::rewind()
Rewinds the file handle (required by iterator interface)
fFile::tossIfDeleted()
Throws an fProgrammerException if the file has been deleted
fFile::valid()
Returns if the file has any lines left (required by iterator interface)
fFile::write()
Writes the provided data to the file

Static Methods

::create() public

Creates an image on the filesystem and returns an object representing it

This operation will be reverted by a filesystem transaction being rolled back.

Signature

fImage create( string $file_path, string $contents )

Parameters

string $file_path The path to the new image
string $contents The contents to write to the image

Throws

fValidationException
When no image was specified or when the image already exists

Overrides

fFile::create()
Creates a file on the filesystem and returns an object representing it.

::getCompatibleMimetypes() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Returns an array of acceptable mime types for the processor that was detected

Signature

array getCompatibleMimetypes( )

Returns

The mime types that the detected image processor can manipulate

::getInfo() protected

Gets the dimensions and type of an image stored on the filesystem

The 'type' key will have one of the following values:

  • {null} (File type is not supported)
  • 'jpg'
  • 'gif'
  • 'png'
  • 'tif'

Signature

mixed getInfo( string $image_path, string $element=NULL )

Parameters

string $image_path The path to the image to get stats for
string $element The element to retrieve: 'type', 'width', 'height'

Returns

An associative array: 'type' => {mixed}, 'width' => {integer}, 'height' => {integer}, or the element specified

Throws

fValidationException
When the file specified is not an image

::isImageCompatible() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Checks to make sure the class can handle the image file specified

Signature

boolean isImageCompatible( string $image )

Parameters

string $image The image to check for incompatibility

Returns

If the image is compatible with the detected image processor

Throws

fValidationException
When the image specified does not exist

::reset() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Resets the configuration of the class

Signature

void reset( )

::setImageMagickDirectory() public

Sets the directory the ImageMagick binary is installed in and tells the class to use ImageMagick even if GD is installed

Signature

void setImageMagickDirectory( string $directory )

Parameters

string $directory The directory ImageMagick is installed in

::setImageMagickTempDir() public

Sets a custom directory to use for the ImageMagick temporary files

Signature

void setImageMagickTempDir( string $temp_dir )

Parameters

string $temp_dir The directory to use for the ImageMagick temp dir

Methods

->__construct() public

Creates an object to represent an image on the filesystem

Signature

fImage __construct( string $file_path, boolean $skip_checks=FALSE )

Parameters

string $file_path The path to the image
boolean $skip_checks If file checks should be skipped, which improves performance, but may cause undefined behavior - only skip these if they are duplicated elsewhere

Throws

fValidationException
When no image was specified, when the image does not exist or when the path specified is not an image

Overrides

fFile::__construct()
Creates an object to represent a file on the filesystem

->append() public

Prevents a programmer from trying to append an image

Signature

void append( mixed $data )

Parameters

mixed $data The data to append to the image

Overrides

fFile::append()
Appends the provided data to the file

->crop() public

Crops the image by the exact pixel dimensions specified

The crop does not occur until saveChanges() is called.

Signature

fImage crop( numeric $new_width, numeric $new_height, numeric|string $crop_from_x, numeric|string $crop_from_y )

Parameters

numeric $new_width The width in pixels to crop the image to
numeric $new_height The height in pixels to crop the image to
numeric|string $crop_from_x The number of pixels from the left of the image to start the crop from, or a horizontal position of 'left', 'center' or 'right'
numeric|string $crop_from_y The number of pixels from the top of the image to start the crop from, or a vertical position of 'top', 'center' or 'bottom'

Returns

The image object, to allow for method chaining

->cropToRatio() public

Crops the biggest area possible from the center of the image that matches the ratio provided

The crop does not occur until saveChanges() is called.

Signature

fImage cropToRatio( numeric $ratio_width, numeric $ratio_height, string $horizontal_position='center', string $vertical_position='center' )

Parameters

numeric $ratio_width The width ratio to crop the image to
numeric $ratio_height The height ratio to crop the image to
string $horizontal_position A horizontal position of 'left', 'center' or 'right'
string $vertical_position A vertical position of 'top', 'center' or 'bottom'

Returns

The image object, to allow for method chaining

->desaturate() public

Converts the image to grayscale

Desaturation does not occur until saveChanges() is called.

Signature

fImage desaturate( )

Returns

The image object, to allow for method chaining

->getDimensions() public

Returns the width and height of the image as a two element array

Signature

array getDimensions( )

Returns

In the format 0 => (integer) {width}, 1 => (integer) {height}

->getHeight() public

Returns the height of the image

Signature

integer getHeight( )

Returns

The height of the image in pixels

->getType() public

Returns the type of the image

Signature

string getType( )

Returns

The type of the image: 'jpg', 'gif', 'png', 'tif'

->getWidth() public

Returns the width of the image

Signature

integer getWidth( )

Returns

The width of the image in pixels

->resize() public

Sets the image to be resized proportionally to a specific size canvas

Will only size down an image. This method uses resampling to ensure the resized image is smooth in appearance. Resizing does not occur until saveChanges() is called.

Signature

fImage resize( integer $canvas_width, integer $canvas_height, boolean $allow_upsizing=FALSE )

Parameters

integer $canvas_width The width of the canvas to fit the image on, 0 for no constraint
integer $canvas_height The height of the canvas to fit the image on, 0 for no constraint
boolean $allow_upsizing If the image is smaller than the desired canvas, the image will be increased in size

Returns

The image object, to allow for method chaining

->rotate() public

Sets the image to be rotated

Rotation does not occur until saveChanges() is called.

Signature

void rotate( integer $degrees )

Parameters

integer $degrees The number of degrees to rotate - 90, 180, or 270

->saveChanges() public

Saves any changes to the image

If the file type is different than the current one, removes the current file once the new one is created.

This operation will be reverted by a filesystem transaction being rolled back. If a transaction is in progress and the new image type causes a new file to be created, the old file will not be deleted until the transaction is committed.

Signatures

fImage saveChanges( string $new_image_type=NULL, integer $jpeg_quality=90, boolean $overwrite=FALSE )

fImage saveChanges( string $new_image_type=NULL, boolean $overwrite=FALSE )

Parameters

string $new_image_type The new file format for the image: 'NULL (no change), 'jpg', 'gif', 'png'`
integer $jpeg_quality The quality setting to use for JPEG images - this may be ommitted
boolean $overwrite If an existing file with the same name and extension should be overwritten

Returns

The image object, to allow for method chaining