fImageclassv1.0.0b19
Represents an image on the filesystem, also provides image manipulation functionality
| 1.0.0b19 | Updated for the new fFile API 3/5/10 |
|---|---|
| 1.0.0b18 | Fixed 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.0b17 | Fixed a couple of bug with using ImageMagick on Windows and BSD machines 3/2/10 |
| 1.0.0b16 | Fixed some bugs with GD not properly handling transparent backgrounds and desaturation of .gif files 10/27/09 |
| 1.0.0b15 | Added getDimensions() 8/7/09 |
| 1.0.0b14 | Performance updates for checking image type and compatiblity 7/31/09 |
| 1.0.0b13 | Updated 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.0b12 | Fixed a bug where calling saveChanges() after unserializing would throw an exception related to the image processor 5/27/09 |
| 1.0.0b11 | Added a crop() method 5/27/09 |
| 1.0.0b10 | Fixed a bug with GD not saving changes to files ending in .jpeg 3/18/09 |
| 1.0.0b9 | Changed processWithGD() to explicitly free the image resource 3/18/09 |
| 1.0.0b8 | Updated for new fCore API 2/16/09 |
| 1.0.0b7 | Changed @ error suppression operator to error_reporting() calls 1/26/09 |
| 1.0.0b6 | Fixed cropToRatio() and resize() to always return the object even if nothing is to be done 1/5/09 |
| 1.0.0b5 | Added check to see if exec() is disabled, which causes ImageMagick to not work 1/3/09 |
| 1.0.0b4 | Fixed saveChanges() to not delete the image if no changes have been made 12/18/08 |
| 1.0.0b3 | Fixed a bug with $jpeg_quality in saveChanges() from 1.0.0b2 12/16/08 |
| 1.0.0b2 | Changed some int casts to round() to fix resize() dimension issues 12/11/08 |
| 1.0.0b | The 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::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::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
->crop() public
Crops the image by the exact pixel dimensions specified
The crop does not occur until saveChanges() is called.
Signature
fImage crop( numeric $crop_from_x, numeric $crop_from_y, numeric $new_width, numeric $new_height )
Parameters
| numeric | $crop_from_x | The number of pixels from the left of the image to start the crop from |
| numeric | $crop_from_y | The number of pixels from the top of the image to start the crop from |
| numeric | $new_width | The width in pixels to crop the image to |
| numeric | $new_height | The height in pixels to crop the image to |
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 )
Parameters
| numeric | $ratio_width | The width ratio to crop the image to |
| numeric | $ratio_height | The height ratio to crop the image to |
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 aappearance. 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
->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 )
fImage saveChanges( string $new_image_type, boolean $overwrite )
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
