Skip to content

Latest commit

 

History

History
174 lines (132 loc) · 6.57 KB

fImage.wiki

File metadata and controls

174 lines (132 loc) · 6.57 KB
Raw

Table of Contents

fImage

<<css mode="next" class="sidebar"></css>> (((

Class Resources <<toc></toc>>

 - '''<a href="/docs/fImage">Class Documentation</a>'''
 - <a href="/api/fImage">API Reference</a>
 - <a href="https://github.com/flourishlib/flourish-classes/blob/master/fImage.php" target="_blank">Source Code</a>

<<toc></toc>>

Filesystem Classes <<toc></toc>>

 - fFilesystem
 - fFile
  - '''fImage'''
 - fDirectory
 - fUpload

)))

The fImage class is a representation of an image file on the filesystem. It provides all of the functionality of the fFile class and adds the ability to perform image manipulation via GD or ImageMagick.

Configuration

As mentioned above, the fImage class provide image manipulation by using either the command line program ImageMagick or the PHP GD extension. fImage prefers ImageMagick since it provides superior performance and does not have the restriction of the PHP memory limit, like the GD extension does.

If the GD extension is not installed and ImageMagick can not be found in a standard location, fImage will need to be configured with the location of ImageMagick. This can be done by passing the ImageMagick binary’s directory to the static method ::setImageMagickDirectory().

In addition to configuring the path to the ImageMagick binaries, it is also possible to set a temporary directory for ImageMagick to use when processing files. The ::setImageMagickTempDir() static method performs this task and takes a single parameter `$temp_dir`.

Image Information

The fImage class includes a few methods to provide basic metadata about the image. ::getWidth() and ::getHeight() provide straight-forward access to image dimensions. ::getDimensions() returns a two-element array of the width, then the height.

The method ::getType() will return a string with the image type. Types include: `'jpg'`, `'gif'`, `'png'` and `'tif'`.

Modification

Probably the most significant functionality of the fImage class is the ability to modify an image. There are currently three different modifications that can be performed: ::crop(), ::cropToRatio(), ::resize() and ::desaturate().

Calling any of these modifications will not actually cause the changes to be written to disk until [#SavingChanges] is called.

Cropping

crop() accepts four parameters, the pixels dimensions for `$new_width` and `$new_height`, `$crop_from_x`, `$crop_from_y`, and will perform pixel-specific cropping.
It is also possible to crop with `$crop_from_x` and `$crop_from_y` being a string position. The possible values for `$crop_from_x` are `left`, `center` and `right`. The possible values for `$crop_from_y` are `top`, `center` and `bottom`.

cropToRatio() will crop the largest rectangle our of an image that conforms to the ratio passed in via `$ratio_width` and `$ratio_height`. By default, the crop is made from the center of the image.
Similar to ::crop(), it is possible to crop to a ratio from a specific position in the image. The third parameter, `$horizontal_position` accepts either `left`, `center` or `right`. The fourth parameter, `$vertical_position`, accepts `top`, `center` or `bottom`.

Desaturating

desaturate() will cause the image to lose all color information and become grayscale.

Resizing

resize() will scale the image proportionally to fit the canvas size defined by the parameters `$canvas_width` and `$canvas_height`. That is to say, the aspect ratio of the image will be retained, and it will not be stretched in either dimension. If either parameter is `empty()` or `0`, the image will be resized to fit the one specified dimension.
`resize()` can also accept an optional third parameter, `$allow_upsizing`. By default `resize()` will only make the image smaller, but when this is `TRUE` the image will be made to fit the dimensions even if it must be increased in size.

Saving Changes

saveChanges() can accept from zero to three parameters. The first optional parameter is the `$new_image_type` which can be `'jpg'`, `'gif'` or `'png'`. If no `$new_image_type` is specified, the image will be resaved in the current format.
If the `'jpg'` image type is specified, there is a second optional parameter, the `$jpeg_quality` to use. If no `$jpeg_quality` is specified, `90` is used as the default.

A third optional parameter, `$overwrite`, accepts a boolean and will cause a file with the same name and type to be overwritten. For example, if the file is currently `image.gif` and you call `saveChanges()` with the parameter `'jpg'` and another file named `image.jpg` exists, by default `image.gif` will be saved with changes as `image_copy1.jpg`. When `$overwrite` is `TRUE`, `image.jpg` will be overwritten.