yana

phpDocumentor v 1.4.0

Class Image

Description

Image wrapper class
This class is an OO wrapper for PHP's image handling functions. Note that this class requires the GD library to be installed in order to work correctly. Not all functions are available in all version of this library. But the class will automatically try a fall-back to an alternative function where possible.
Also note, that this class will NOT output any error messages unless a fatal error is encountered and instead will report error to the logs. This is a intended behaviour, as any output (e.g. an error message) from the script would result in a broken image file, when the image is directly put to the user's browser.
So when you are working with this class: in case you encounter an error and want to know the cause of it, please activate the program's logging feature via the administrator's menu, reproduce the error and see the logs for the entry that describes the problem.
The following image types are currently supported:
  • bmp
  • gif
  • jpeg
  • png
  • since: 2.8.7
  • access: public
Object
   |
   --Image
Variable Summary
int $aqua
int $black
int $blue
int $fuchsia
int $gray
int $green
int $grey
int $lime
int $maroon
int $navy
int $olive
int $purple
int $red
int $silver
int $teal
int $white
int $yellow
Method Summary
  • Image Image ([string $filename = null], [string $imageType = null])
  • bool applyFilter (int $filter, int $arg1, int $arg2, int $arg3)
  • bool blur (float $ammount)
  • bool brightness (float $ammount)
  • void clearCanvas ()
  • Object cloneObject ()
  • bool colorize (int $r, int $g, int $b)
  • float compareImage (Image|string $otherImage)
  • bool contrast (float $ammount)
  • bool copyPalette (Image|string|resource $sourceImage)
  • bool copyRegion (Image|string|resource $sourceImage, [int $sourceX = null], [int $sourceY = null], [int $width = null], [int $height = null], [int $destX = null], [int $destY = null], [float $opacity = null])
  • bool drawEllipse (int $x, int $y, int $width, [int $height = null], [int $color = null], [int $fillColor = null], [int $start = null], [int $end = null])
  • bool drawFormattedString (string $text, [int $x = null], [int $y = null], [int $color = null], [string $fontfile = null], [int $fontsize = 10], int $angle)
  • bool drawLine (int $x1, int $y1, int $x2, int $y2, [int $color = null])
  • bool drawPoint (int $x, int $y, [int $color = null])
  • bool drawPolygon (array $points, int $x, int $y, [int $color = null], [int $fillColor = null])
  • bool drawRectangle (int $x, int $y, int $width, [int $height = null], [int $color = null], [int $fillColor = null])
  • bool drawString (string $text, [int $x = null], [int $y = null], [int $color = null], [int $font = null], [bool $asVerticalString = false])
  • bool enableAlpha ([bool $isEnabled = true], [bool $saveAlpha = null])
  • bool enableAntialias ([bool $isEnabled = true])
  • bool enableInterlace ([bool $isInterlaced = true])
  • bool equals (object $anotherObject)
  • bool exists ()
  • array fill (int $fillColor, int $x, int $y, [int $borderColor = null])
  • bool flipX ()
  • bool flipY ()
  • int|bool(false) getBackgroundColor ()
  • int|bool(false) getColor (int $r, int $g, int $b, [float $opacity = null])
  • int|bool(false) getColorAt (int $x, int $y)
  • array|bool(false) getColorValues (int $color)
  • int|bool(false) getFontHeight (int $font)
  • int|bool(false) getFontWidth (int $font)
  • int|bool(false) getHeight ()
  • int|bool(false) getLineWidth ()
  • int|bool(false) getPaletteSize ()
  • string getPath ()
  • resource|bool(false) getResource ()
  • array getSize (string $filename)
  • int|bool(false) getTransparency ()
  • int|bool(false) getWidth ()
  • bool hasAlpha ()
  • bool isBroken ()
  • bool isInterlaced ()
  • bool isTruecolor ()
  • bool monochromatic (int $r, int $g, int $b)
  • bool multiply (int $r, int $g, int $b)
  • bool negate ()
  • string|bool(false) outputToFile (string $filename, [string $imageType = null])
  • bool outputToScreen ([string $imageType = null])
  • bool reduceColorDepth (int $ammount, [bool $dither = true])
  • bool replaceColor (int $replacedColor, int $newColor)
  • bool replaceIndexColor (int $replacedColor, array|int $newColor)
  • bool resize ([int $width = null], [int $height = null])
  • bool resizeCanvas ([int $width = null], [int $height = null], [int $paddingLeft = null], [int $paddingTop = null], [array $canvasColor = null])
  • bool resizeImage ([int $width = null], [int $height = null])
  • bool rotate (float $angle)
  • bool setBackgroundColor ([int $backgroundColor = null], [bool $replaceOldColor = true])
  • bool setBrush (string|Image|Brush|resource $brush)
  • bool setGamma (float $gamma)
  • bool setLineStyle ()
  • bool setLineWidth (int $width)
  • bool setTransparency ([int|array $transparency = null])
  • bool sharpen (float $ammount)
  • void toGrayscale ()
  • void toGreyscale ()
  • string toString ()
  • string|int uploadFile (string $fromId, string $toFilename, [string $imageType = null], [int $maxSize = null], [int $width = null], [int $height = null], [bool $keepAspectRatio = true], [array $backgroundColor = null])

Variables

int $aqua = null
aqua = #00ffff
color
  • final:
  • access: public
int $black = null
black = #000000
color
  • final:
  • access: public
int $blue = null
blue = #0000ff
color
  • final:
  • access: public
int $fuchsia = null
fuchsia = #ff00ff
color
  • final:
  • access: public
int $gray = null
gray = #808080
color
  • final:
  • access: public
int $green = null
green = #008000
color
  • final:
  • access: public
int $grey = null
grey = #808080
color
  • final:
  • access: public
int $lime = null
lime = #00ff00
color
  • final:
  • access: public
int $maroon = null
maroon = #800000
color
  • final:
  • access: public
int $navy = null
navy = #008080
color
  • final:
  • access: public
int $olive = null
olive = #808000
color
  • final:
  • access: public
int $purple = null
purple = #800080
color
  • final:
  • access: public
int $red = null
red = #ff0000
color
  • final:
  • access: public
int $silver = null
silver = #c0c0c0
color
  • final:
  • access: public
int $teal = null
teal = #008080
color
  • final:
  • access: public
int $white = null
white = #ffffff
color
  • final:
  • access: public
int $yellow = null
yellow = #ffff00
color
  • final:
  • access: public

Methods

create a new instance of this class
Image Image (
[string $filename = null], [string $imageType = null]
)
List of parameters:
Name Type Description
$filename string name of the source file
$imageType string type of the image
Description:
The argument $filename determines wich file to take the input from. If $filename is not provided, an empty truecolor image with white background and a dimension of 300x200px is created.
The argument $imageType can be on of the following.
  • bmp
  • gif
  • jpeg
  • png
If no image type is set, the function will try to determine the correct type of the file automatically, 1st by checking the file extension and in case this did not work 2nd by checking the file header. If all this fails it writes an entry to the logs and creates an error image instead.
NOTE: it DOES NOT produces an error message, as this would result in a broken image, if the image was printed!
To check wether or not an image is broken, use
  1.  if ($myImage->isBroken(=== true{
  2.      // handle broken image
  3.  }
apply a filter
bool applyFilter (
int $filter, int $arg1, int $arg2, int $arg3
)
List of parameters:
Name Type Description
$filter int a constant (see list)
$arg1 int depends on filter
$arg2 int depends on filter
$arg3 int depends on filter
Description:
This is an OO-style alias of PHP's imagefilter() function. See the PHP manual for a full description.
$filter can be (among others) one of the following:
Note: this is only available with PHP 5. If you are using PHP 4, check with the alternative functions named above.
Returns bool(true) on success and bool(false) on error.
blur the image
bool blur (
float $ammount
)
List of parameters:
Name Type Description
$ammount float effect strength
Description:
This makes the image look smoother. The argument $ammount is any float 0.0 through 1.0, which translates to 0% through 100%.
  • access: public
brighten / darken the image
bool brightness (
float $ammount
)
List of parameters:
Name Type Description
$ammount float effect strength
Description:
Adds or removes white from the image.
The argument $ammount is a float between -1.0 and 1.0. Which you might translate to -100% through 100%.
This has the same effect as calling Image::colorize($r, $g, $b), with $r, $b, $g being identical values.
Returns bool(true) on success and bool(false) on error.
  • access: public
This function produces a new image
void clearCanvas ()
Description:
The old image is deleted and replaced by a new one. Be warned: all previous changes to the image will be lost!
  • access: public
clone this object
Object cloneObject ()
Description:
Creates a copy of this object. You are encouraged to reimplement this for each subclass.
  • access: public

Redefinition of: Object::cloneObject()

colorize the image
bool colorize (
int $r, int $g, int $b
)
List of parameters:
Name Type Description
$r int red value
$g int green value
$b int blue value
Description:
This adds the specified color to the image, shaded in the color provided.
The arguments $r, $g, $b can be any integer of -255 through 255.
Returns bool(true) on success and bool(false) on error.
  • access: public
compare this image to another
float compareImage (
Image|string $otherImage
)
List of parameters:
Name Type Description
$otherImage Image|string filename or image object
Description:
This function compare the image to another image on a pixel by pixel basis. It returns the difference between booth images in percent.
The result is returned as a float value, where 0.0 translates to 0% (images are exactly the same) and 1.0 translates to 100% (images are totally different).
On error the function returns bool(false).
I would suggest to consider two images equal, if the difference is not greater than 1% (or in other words, if the images are 99% the same). Images with less than 10% difference should be similar. E.g. one has sharper edges, or one is lighter than the other. Any value higher than 10% should indicate that both images are different.
WARNING: since this function compares every pixel it is very slow for large images. It's use is suggested for testing and debugging issues only.
  • since: 2.9.9
  • access: public
add / remove contrast from the image
bool contrast (
float $ammount
)
List of parameters:
Name Type Description
$ammount float effect strength
Description:
Adds or removes grey from the image.
The argument $ammount is a float between -1.0 and 1.0. Which you might translate to -100% through 100%.
Returns bool(true) on success and bool(false) on error.
  • access: public
copy palette
bool copyPalette (
Image|string|resource $sourceImage
)
List of parameters:
Name Type Description
$sourceImage Image|string|resource the image to copy the palette from
Description:
This copies the palette from the source image to this image.
The argument $sourceImage can be another Image object, a filename, or an image resource.
Returns bool(true) on success and bool(false) on error.
  • access: public
copy one portion of an image to another
bool copyRegion (
Image|string|resource $sourceImage, [int $sourceX = null], [int $sourceY = null], [int $width = null], [int $height = null], [int $destX = null], [int $destY = null], [float $opacity = null]
)
List of parameters:
Name Type Description
$sourceImage Image|string|resource filename or image resource
$sourceX int horizontal position in pixel
$sourceY int vertical position in pixel
$width int horizontal dimension in pixel
$height int vertical dimension in pixel
$destX int horizontal position in pixel
$destY int vertical position in pixel
$opacity float alpha value in percent
Description:
This is an OO-style alias of PHP's imagecopymerge() function. See the PHP manual for a full description.
The argument $sourceImage can be another Image object, a filename, or an image resource.
If $width and / or $height is NULL or not provided, then they are set to cover the full size of the image.
If $sourceX and / or $sourceY is NULL or not provided, then they are set to 0 (the upper left corner).
If $destX and / or $destY is NULL or not provided, then they are set to the same values as $sourceX and $sourceY.
The $opacity parameter is available for truecolor images only. It is a float between 0.0 (completely opaque) and 1.0 (completely transparent). You may translate this to 0% through 100% opacity. Note that opacity only applies when alpha blending has has not been disabled and the underlying function is available.
To copy the whole source image to the current image, just write:
  1.  $image->copyRegion($anotherImage);
  2.  // $image now is a copy of $anotherImage
Returns bool(true) on success and bool(false) on error.
  • access: public
draw an ellipse
bool drawEllipse (
int $x, int $y, int $width, [int $height = null], [int $color = null], [int $fillColor = null], [int $start = null], [int $end = null]
)
List of parameters:
Name Type Description
$x int horizontal position
$y int vertical position
$width int horizontal dimension in pixel
$height int vertical dimension in pixel
$color int the color of the contour line
$fillColor int the color to flood fill the ellipse with
$start int angle in degrees (start)
$end int angle in degrees (end)
Description:
This draws an ellipse at position ($x px, $y px).
With the dimensions $width px to $height px. Note that you can set $width = $height to create a circle. Setting $height = NULL does the same.
The $color is an integer value, that you can get via the function Image::getColor().
In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.
Example:
  1.  $image new Image();
  2.  $image->drawEllipse(202030null$image->black);
The same applies to $fillColor. When provided, a filled object is created. You can create object that are not filled, by setting this to NULL.
Setting $start and $end will create an arcus, that starts at $start degrees and goes to $end degrees. Both values can be NULLed. Note that $start and $end can also be negative.
  • access: public
draw a formatted text string with a true-type font
bool drawFormattedString (
string $text, [int $x = null], [int $y = null], [int $color = null], [string $fontfile = null], [int $fontsize = 10], int $angle
)
List of parameters:
Name Type Description
$text string the text to draw
$x int horizontal position
$y int vertical position
$color int the text color
$fontfile string path and name of a true-type (*.ttf) font
$fontsize int size
$angle int rotation 0 through 360 degrees
Description:
This is the same as Image::drawString() except, that it allows some true-type font of your choosing to be used, accepts a custom font size and allows to freely choose an angle of rotation.
The rotation is performed anticlockwise. To create a text that flows straight up, set $angle to 90.
The default font is 'tahoma'. The path to the font file needs to start with a '/' sign.
Note that $fontfile my also be just the name of font, like 'tahoma', 'arial', or 'helvetica'. If the name instead of the file is provided, this function will try to use a true-type font of the same name, which is installed on the current system. Of course this requires that the font actually IS installed on the system.
  • access: public
draw a line
bool drawLine (
int $x1, int $y1, int $x2, int $y2, [int $color = null]
)
List of parameters:
Name Type Description
$x1 int horizontal position (start)
$y1 int vertical position (start)
$x2 int horizontal position (end)
$y2 int vertical position (end)
$color int the line color
Description:
This draws a straight line at position ($x px, $y px).
The line has the color set by the argument $color. This defaults to black.
  • access: public
draw a point (aka paint a pixel)
bool drawPoint (
int $x, int $y, [int $color = null]
)
List of parameters:
Name Type Description
$x int horizontal position (left value)
$y int vertical position (top value)
$color int the point color
Description:
This paints the pixel at position ($x px, $y px) with a $color. This color defaults to black.
  • access: public
draw a polygon
bool drawPolygon (
array $points, int $x, int $y, [int $color = null], [int $fillColor = null]
)
List of parameters:
Name Type Description
$points array a list of vertices
$x int horicontal position
$y int vertical position
$color int color of contour line
$fillColor int inner color
Description:
This draws a polygon at position ($x px, $y px).
$points is a two dimensional array of the vertices. Example:
  1.  $points array(
  2.  => array100  ),
  3.  => array2010 ),
  4.  => array(  010 )
  5.  );
  6.  $image new Image();
  7.  $image->drawPolygon($points);
  8.  $image->outputToScreen();
(The code above will output a triangle.)
The $color is an integer value, that you can get via the function Image::getColor().
In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.
Example:
  1.  $image new Image();
  2.  $image->drawPolygon($points$image->black);
The same applies to $fillColor. When provided, a filled object is created. You can create object that are not filled, by setting this to NULL.
  • access: public
draw a rectangle
bool drawRectangle (
int $x, int $y, int $width, [int $height = null], [int $color = null], [int $fillColor = null]
)
List of parameters:
Name Type Description
$x int horicontal position in pixel
$y int vertical position in pixel
$width int horizontal dimension in pixel
$height int vertical dimension in pixel
$color int color of contour line
$fillColor int inner color
Description:
This draws a rectangle at position ($x px, $y px).
With the dimensions $width px to $height px. Note that you can set $width = $height to create a square. Setting $height = NULL does the same.
The $color is an integer value, that you can get via the function Image::getColor().
In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.
Example:
  1.  $image new Image();
  2.  $image->drawRectangle(101030null$image->black);
The same applies to $fillColor. When provided, a filled object is created. You can create object that are not filled, by setting this to NULL.
  • access: public
draw a text string
bool drawString (
string $text, [int $x = null], [int $y = null], [int $color = null], [int $font = null], [bool $asVerticalString = false]
)
List of parameters:
Name Type Description
$text string the text to draw
$x int horizontal position
$y int vertical position
$color int the text color
$font int font size (1 through 5)
$asVerticalString bool switch between horizontal and vertical print
Description:
This draws a text string at position ($x px, $y px).
The string has the color set by the argument $color. This defaults to black.
The $color is an integer value, that you can get via the function Image::getColor().
In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.
Example:
  1.  $image new Image();
  2.  $image->drawString('Hello World!'00$image->black);
The argument $font determines the font type and size. The values 1-5 are used for a predefined system font. Where 1 is the smallest font-size and 5 is the largest. The font itself belongs to the sans-serif family. Note that you can load custom fonts using the PHP function imageloadfont(). The argument $font defaults to 2, which is a 10px font.
The argument $asVerticalString is used to switch from printing text horizontal to vertical. Note that vertical strings are rotated 90 left (anticlockwise). This means they will start at ($x px, $y px) upwards, so you should make sure, there is enough space for the string on your image above the starting point.
All arguments except $text may be skipped by assigning the NULL value.
  • access: public
enable / disable alpha blending
bool enableAlpha (
[bool $isEnabled = true], [bool $saveAlpha = null]
)
List of parameters:
Name Type Description
$isEnabled bool on / off
$saveAlpha bool on / off
Description:
Enables alpha blending if set to bool(true) and disables it when set to bool(false).
Works only with truecolor images.
If $saveAlpha is true and the output is a PNG image, the alpha channel information will get saved with the file, otherwise not. Note that this setting only affects PNG images.
You should be aware, that IE 6.0 and other older browsers do not support alpha channels in PNG images by default.
Returns bool(true) on success and bool(false) on error.
  • access: public
enable / disable antialiasing
bool enableAntialias (
[bool $isEnabled = true]
)
List of parameters:
Name Type Description
$isEnabled bool on / off
Description:
Enables antialiasing if set to bool(true) and disables it when set to bool(false).
Works only with truecolor images.
Returns bool(true) on success and bool(false) on error.
  • access: public
switch interlacing on / off
bool enableInterlace (
[bool $isInterlaced = true]
)
List of parameters:
Name Type Description
$isInterlaced bool on / off
Description:
If $isInterlaced is true, interlacing is set to on, otherwise set to off.
If the image is a JPEG, this setting will set the output to be a progressive image.
Returns bool(true) on success and bool(false) on error.
  • access: public
compare with another object
bool equals (
object $anotherObject
)
List of parameters:
Name Type Description
$anotherObject object any object or var you want to compare
Description:
Returns bool(true) if this object and $anotherObject are the booth object which have an image resource that is the same, or $anotherObject is an image resource and identical to the one of this object.
Retunrs bool(false) otherwise.
  • access: public

Redefinition of: Object::equals()

return true, if the image exists
bool exists ()
Description:
  • access: public
fill with a color
array fill (
int $fillColor, int $x, int $y, [int $borderColor = null]
)
List of parameters:
Name Type Description
$fillColor int the filled area will get this color
$x int horicontal position
$y int vertical position
$borderColor int flood fill will stop at this color
Description:
This does a flood fill at position ($x px, $y px).
The $fillColor is an integer value, that you can get via the function Image::getColor().
In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.
Example:
  1.  $image new Image();
  2.  $image->fill($image->white);
If $borderColor is defined, flood fill will stop at the this color, otherwise it will stop at any color that is different from pixel ($x px, $y px).
  • access: public
flip the image horizontally
bool flipX ()
Description:
Returns bool(true) on success and bool(false) on error.
  • access: public
flip the image vertically
bool flipY ()
Description:
Returns bool(true) on success and bool(false) on error.
  • access: public
get current background color
int|bool(false) getBackgroundColor ()
Description:
Returns the current background color as an integer or bool(false) on error.
get a color for the current index
int|bool(false) getColor (
int $r, int $g, int $b, [float $opacity = null]
)
List of parameters:
Name Type Description
$r int red value
$g int green value
$b int blue value
$opacity float alpha value
Description:
This is an OO-style alias of PHP's imagecolorallocate() function. See the PHP manual for a full description.
The $opacity parameter is available as of PHP 4.3.2. It is a float between 0.0 (completely opaque) and 1.0 (completely transparent). You may translate this to 0% through 100% opacity. Note that opacity only applies when alpha blending has has not been disabled and the underlying function is available.
If the current palette already has the specified color, the existing color will be returned. Otherwise the new color will get appended to the palette.
Returns bool(false) on error.
  • access: public
get color at pixel ($x,$y)
int|bool(false) getColorAt (
int $x, int $y
)
List of parameters:
Name Type Description
$x int horicontal position
$y int vertical position
Description:
This is an OO-style alias of PHP's imagecolorat() function. See the PHP manual for a full description.
This function returns bool(false) on error.
  • access: public
get color values (red,green,blue,alpha)
array|bool(false) getColorValues (
int $color
)
List of parameters:
Name Type Description
$color int a color resource
Description:
This is an OO-style alias of PHP's imagecolorsforindex() function. See the PHP manual for a full description.
Example:
  1.  $image new Image();
  2.  print_r($image->getColorValues($image->white));
Will output:
  1.  Array
  2.  (
  3.      [red=> 255
  4.      [green=> 255
  5.      [blue=> 255
  6.      [alpha=> 0
  7.  )
  • access: public
get font width
int|bool(false) getFontHeight (
int $font
)
List of parameters:
Name Type Description
$font int a font resource
Description:
This is an OO-style alias of PHP's imagefontheight() function. See the PHP manual for a full description.
The argument $font determines the font type. The values 1-5 are used for a predefined system font. Where 1 is the smallest font-size and 5 is the largest. The font itself belongs to the sans-serif family. Note that you can load custom fonts using the PHP function imageloadfont().
This function is usefull to calculate how much space a string is going to take on the picture when using this font.
  • access: public
get font width
int|bool(false) getFontWidth (
int $font
)
List of parameters:
Name Type Description
$font int a font resource
Description:
This is an OO-style alias of PHP's imagefontheight() function. See the PHP manual for a full description.
The argument $font determines the font type. The values 1-5 are used for a predefined system font. Where 1 is the smallest font-size and 5 is the largest. The font itself belongs to the sans-serif family. Note that you can load custom fonts using the PHP function imageloadfont().
This function is usefull to calculate how much space a string is going to take on the picture when using this font.
  • access: public
get image height
int|bool(false) getHeight ()
Description:
Returns the image's vertical dimension in pixel or bool(false) on error.
  • access: public
get current line width
int|bool(false) getLineWidth ()
Description:
Returns the current line width in pixel as an integer value.
Returns bool(false) on error.
  • access: public
get number of colors in palette
int|bool(false) getPaletteSize ()
Description:
Returns bool(false) on error.
For palette images the number of colors is the number of colors used in the current image. For truecolor images the maximum number of colors is returned, which is always 16 million.
Note that if you reduce the color depth using $image->reduceColorDepth($number), This function may NOT return $number, but instead the number of colors that are actually used in the image, which may be less then $number.
  • access: public
get filename
string getPath ()
Description:
  • access: public
get the image resource
resource|bool(false) getResource ()
Description:
This returns the image resource of the object, or bool(false) on error.
  • access: public
get image info
array getSize (
string $filename
)
List of parameters:
Name Type Description
$filename string relative file path
Description:
This is an OO-style alias of PHP's getimagesize() function. See the PHP manual for a full description.
The following two lines are equal:
  1.  $imgInfo Image::getSize('foo.png');
  2.  $imgInfo getimagesize('foo.png');
Just choose the style that you prefer.
  • access: public
get current transparency color
int|bool(false) getTransparency ()
Description:
Returns bool(false) on error.
  • access: public
get image width
int|bool(false) getWidth ()
Description:
Returns the image's horizontal dimension in pixel or bool(false) on error.
  • access: public
Check if image has alpha channel
bool hasAlpha ()
Description:
This returns bool(true) if alpha channel is turned on for the current image. Returns bool(false) otherwise.
Compatibility note: This function has been renamed in version 2.8.8 from "hasAlphaChannel()" to "hasAlpha()".
  • access: public
return true, if the image is broken
bool isBroken ()
Description:
Returns bool(true) if the image type was not recognized. Returns bool(false) otherwise.
  • access: public
Check if image is interlaced
bool isInterlaced ()
Description:
This returns bool(true) if interlacing is turned on for the current image. Returns bool(false) otherwise.
  • access: public
check if image is truecolor
bool isTruecolor ()
Description:
Returns bool(true) if the image is truecolor and bool(false) otherwise.
Truecolor images are e.g. JPEG images while GIF is not. Some functions won't work with non-truecolor images.
  • access: public
create a monochromatic image
bool monochromatic (
int $r, int $g, int $b
)
List of parameters:
Name Type Description
$r int red value
$g int green value
$b int blue value
Description:
This produces a monochromatic version of the image, shaded in the color provided.
The arguments $r, $g, $b can be any integer of 0 through 255.
Returns bool(true) on success and bool(false) on error.
  • access: public
multiply the palette values with a color
bool multiply (
int $r, int $g, int $b
)
List of parameters:
Name Type Description
$r int red value
$g int green value
$b int blue value
Description:
The color provided multiplies with each color in the palette. For example, this is usefull to filter colors.
Extract the green channel of an image:
  1.  $image->multiply(02550);
Removing some red from an image will remove a red stitch and shift the colors towards a cold turquoise:
  1.  $image->multiply(200255255);
Shifting cold blue colors towards warm orange colors:
  1.  $image->multiply(255200150);
The arguments $r, $g, $b can be any integer of 0 through 255.
Returns bool(true) on success and bool(false) on error.
  • access: public
procude negative image
bool negate ()
Description:
This function negates all colors.
Returns bool(true) on success and bool(false) on error.
  • access: public
output image to a file
string|bool(false) outputToFile (
string $filename, [string $imageType = null]
)
List of parameters:
Name Type Description
$filename string name of the output file
$imageType string can be on of "png", "jpg", "gif", "bmp"
Description:
Returns the name of the output file on success and bool(false) on error.
You may leave off the file extension. If so the function will determine the correct extension by itself and append it automatically to the argument $filename.
If the file already exists, it will get replaced.
The optional argument $imageType can be used to set a prefered image type.
If no prefered image type is set, or the prefered image type is not available, then this function will automatically try to create a PNG image. If PNG is not available it will automatically try fall back to another type. PNG will fall back to JPEG, JPEG to GIF, GIF to BMP. Only if nothing of the above worked, it will give up and returns bool(false). Otherwise bool(true) is returned.
  • access: public
output image to browser
bool outputToScreen (
[string $imageType = null]
)
List of parameters:
Name Type Description
$imageType string can be on of "png", "jpg", "gif", "bmp"
Description:
Returns bool(true) on success and bool(false) on error.
The optional argument $imageType can be used to set a prefered image type.
If no prefered image type is set, or the prefered image type is not available, then this function will automatically try to create a PNG image. If PNG is not available it will automatically fall back. PNG will fall back to JPEG, JPEG to GIF, GIF to BMP. If nothing of the above worked it gives up and returns bool(false).
  • access: public
reduce color depth to value
bool reduceColorDepth (
int $ammount, [bool $dither = true]
)
List of parameters:
Name Type Description
$ammount int effect strength
$dither bool on / off
Description:
Returns bool(true) on success and bool(false) on error.
Reduces the color depth of the current image to $ammount colors. The argument $ammount is an integer 2 through 256.
The argument $dither triggers whether or not dithering is used while reducing the colors for the current image.
  • access: public
replace a color
bool replaceColor (
int $replacedColor, int $newColor
)
List of parameters:
Name Type Description
$replacedColor int index of replaced color
$newColor int index of the new color
Description:
This replaces the replaced color by a new color.
To be more technical, this is done by setting the replaced color as transparent, setting the new color as background and merging the results to a new image. Then reseting transparency and background color to the previously set values.
This may take some time - if you prefer a more performant solution, see Image::replaceIndexColor() instead.
Returns bool(true) on success and bool(false) on error.
replace one palette color by another
bool replaceIndexColor (
int $replacedColor, array|int $newColor
)
List of parameters:
Name Type Description
$replacedColor int index of replaced color
$newColor array|int the color that should be assigned
Description:
This replaces the palette color with the index $replacedColor by the color with the index $newColor. Note that $newColor can also be an associative array with the keys 'red', 'green' and 'blue'.
Returns bool(true) on success and bool(false) on error.
Note that this only works on palette (non-truecolor) images and thus returns false if the image is truecolor. Also note, that all images are converted to truecolor by default.
Examples:
  1.  $image->replaceIndexColor(0$image->blue);
  2.  $array $image->getColorValues($image->red);
  3.  $image->replaceIndexColor(1$array);
  4.  $image->replaceIndexColor(2array('red'=>0,'green'=>255,'blue'=>100));
  • access: public
Resize the image
bool resize (
[int $width = null], [int $height = null]
)
List of parameters:
Name Type Description
$width int horizontal dimension in pixel
$height int vertical dimension in pixel
Description:
This resizes the image to $width x $height.
You may set either $width or $height to NULL to get a proportional resize.
Returns bool(false) on error.
IMPORTANT NOTE: this function resets some settings. E.g. transparency, color depth a.s.o. will be lost.
  • access: public
Resize the canvas
bool resizeCanvas (
[int $width = null], [int $height = null], [int $paddingLeft = null], [int $paddingTop = null], [array $canvasColor = null]
)
List of parameters:
Name Type Description
$width int horizontal dimension in pixel
$height int vertical dimension in pixel
$paddingLeft int horizontal offset
$paddingTop int vertical offset
$canvasColor array array of red, green, yellow values (0 through 255) to identify the canvas color, defaults to background color
Description:
This resizes the canvas to $width x $height.
You may set either $width or $height to NULL to get a proportional resize. If $width or $height is smaller than the current value, the parts of the image that do not fit will get cut.
The $paddingLeft and $paddingTop parameters set left and top padding for the canvas. Setting both to 0 will position the left-top corner of the original image at the point (0, 0) on the new image. If the original image was bigger than the new, the parts at the right and the bottom the are outside the canvas will get cut. Note that you may use negative numbers here. Still you may not completely move the image outside the canvas.
If $left and/or $top are not provided, the image will get copied to the center of the canvas.
Examples:
  1.  // original image is 300x200px
  2.  // this will return true, but does nothing at all
  3.  $image->resizeCanvas(300);
  4.  // resize to 150x100px
  5.  $image->resizeCanvas(150);
  6.  // same effect
  7.  $image->resizeCanvas(null100);
  8.  // cut 20px off the top
  9.  // the image is centered horizontally
  10.  $image->resizeCanvas(nullnullnull-20);
  11.  // cut 50px off the left
  12.  // the image is centered vertically
  13.  $image->resizeCanvas(nullnull-50);
  14.  // cut 50px off the right
  15.  // the image is centered vertically
  16.  $image->resizeCanvas(nullnull50);
  17.  // combination of all
  18.  $image->resizeCanvas(20010010-5);
  19.  // these will return false
  20.  $image->resizeCanvas(0);
  21.  $image->resizeCanvas(-1);
  22.  // padding value out of range
  23.  $image->resizeCanvas(nullnull301);
  24.  $image->resizeCanvas(nullnull300);
  25.  $image->resizeCanvas(nullnullnull-200);
Returns bool(false) on error.
  • since: 2.8.8
  • access: public
Resize the image
bool resizeImage (
[int $width = null], [int $height = null]
)
List of parameters:
Name Type Description
$width int horizontal dimension in pixel
$height int vertical dimension in pixel
Description:
alias of Image::resize()
Rotate the image
bool rotate (
float $angle
)
List of parameters:
Name Type Description
$angle float angle of rotation in degree
Description:
This rotates the image anticlockwise by $angle degrees.
This function became available with PHP 4.3.
  • access: public
set current background color
bool setBackgroundColor (
[int $backgroundColor = null], [bool $replaceOldColor = true]
)
List of parameters:
Name Type Description
$backgroundColor int index of new background color
$replaceOldColor bool
Description:
If you don't specify a background color, than the color is reset.
By default the background color will be set to the transparent color of the image if it has any. Otherwise it defaults to white.
If the argument $replaceOldColor is set to true, it will replace the all pixel of the previous background color with the new one. It it is set to false, the new background color will get appended and all pixel of the old color will remain as is.
Returns bool(true) on success and bool(false) on error.
  • access: public
set current brush
bool setBrush (
string|Image|Brush|resource $brush
)
List of parameters:
Name Type Description
$brush string|Image|Brush|resource a brush resource
Description:
Sets the brush used by imageline(), imagepolygon() et cetera to the image $brush.
The argument $brush can be a filename of the image that you want to use as the brush to use, or another image object. In addition $brush may also be an image resource.
Returns bool(true) on success and bool(false) on error.
  • access: public
set gamma correction
bool setGamma (
float $gamma
)
List of parameters:
Name Type Description
$gamma float effect strength
Description:
Gamma can be any positive float 0.1 trough 10.0 The base is always 1.0 (100%). So e.g. calling setGamma(0.1) sets the gamma of the image to 10% and calling setGamma(2.0) sets the gamma to 200%. To reset the gamma value call setGamma(1.0).
This function only works on truecolor images.
Returns bool(true) on success and bool(false) on error.
  • access: public
set line style
bool setLineStyle ()
Description:
This is an OO-style alias of PHP's imagesetstyle() function. See the PHP manual for details.
Example:
  1.  $r $image->red;
  2.  $w $image->white;
  3.  // dotted line
  4.  $image->setLineStyle($r$w);
  5.  // 3px dashed line
  6.  $image->setLineStyle($r$r$r$w$w$w);
To reset the line style, call this function with no arguments.
  • access: public
set line width
bool setLineWidth (
int $width
)
List of parameters:
Name Type Description
$width int size in pixel
Description:
Sets the line width of the current brush to $width. The setting will apply to whatever you draw, until you call this function again.
Returns bool(true) on success and bool(false) on error.
  • access: public
set transparency to a color
bool setTransparency (
[int|array $transparency = null]
)
List of parameters:
Name Type Description
$transparency int|array new transparent color
Description:
Returns bool(true) on success and bool(false) on error.
The $transparency color is an integer value, that you can get via the function Image::getColor().
In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.
Example:
  1.  $image new Image();
  2.  $image->setTransparency($image->white);
If $transparency is not set, the current background color will be used instead.
  • access: public
sharpen the image
bool sharpen (
float $ammount
)
List of parameters:
Name Type Description
$ammount float effect strength
Description:
This sharpens the image. The argument $ammount is any float 0.0 through 1.0, which translates to 0% through 100%.
  • access: public
convert a colored image to grayscale
void toGrayscale ()
Description:
This converts the palette colors to gray values.
alias of Image::toGrayscale()
void toGreyscale ()
Description:
get a string representation of this object
string toString ()
Description:
This function is intended to be called when the object is used in a string context.
  • access: public

Redefinition of: Object::toString()

upload an image file
string|int uploadFile (
string $fromId, string $toFilename, [string $imageType = null], [int $maxSize = null], [int $width = null], [int $height = null], [bool $keepAspectRatio = true], [array $backgroundColor = null]
)
List of parameters:
Name Type Description
$fromId string identifier of the form-field from which the file has been sent
$toFilename string the path and filename to output the file to
$imageType string prefered type of the output file
$maxSize int maximum size of uploaded files in byte
$width int horizontal dimension of the output image in pixel
$height int vertical dimension of the output image in pixel
$keepAspectRatio bool vertical dimension of the output image in pixel
$backgroundColor array array of red, green, yellow values (0 through 255) to identify the background color, defaults to white
Description:
The purpose of this method is to handle an uploaded image.
The image is taken from the $_FILES array at the index provided by the argument $fromId ($_FILES[$fromId]). The argument is case-insensitive.
The method converts the image to the type given by the argument $imageType, which currently can be "gif", "png" or "jpg".
The image is resized to the dimensions given by the arguments $width x $height. If you set one of these to NULL, the other one will be determined automatically. If you leave booth to NULL, the image will not be resized at all.
The argument $keepAspectRatio triggers how the image is resized. If it is false, the image will be stretched or compressed to the dimensions of the output image. If it is true, will be resized proportionally and the canvas will expanded to the size of the output instead, if necessary.
When using the setting true (which is the default), you may provide a background color for the canvas using the argument $backgroundColor. To do so, provide an array with the red, green and yellow values. Example: array(255, 255, 255) is "white".
The converted and resized image is then copied to the path given by the argument $toFilename.
The method returns the name of the output file on success and an integer constant on error.
Possible error codes returned by this method are:
  1. file upload failed => value of $_FILES[$fromId]['error']
  2. uploaded file exceeds maximum file size => UPLOAD_ERR_SIZE
  3. uploaded file is not a recognized image => UPLOAD_ERR_FILE_TYPE
  4. unable to write to target directory => UPLOAD_ERR_INVALID_TARGET
  5. misc. (unexpected) errors => UPLOAD_ERR_OTHER
You may leave off the file extension. If so the function will determine the correct extension by itself and append it automatically to the argument $filename.
If the file already exists, it will get replaced.
The optional argument $imageType can be used to set a prefered image type.
If no prefered image type is set, or the prefered image type is not available, then this function will automatically try to create a PNG image. If PNG is not available it will automatically try fall back to another type. PNG will fall back to JPEG, JPEG to GIF, GIF to BMP. Only if nothing of the above worked, it will give up and returns bool(false). Otherwise bool(true) is returned.
Example of usage:
HTML-Code:
  1.  <form method="POST" action="%PHP_SELF%" enctype="multipart/form-data">
  2.  ...
  3.  Upload image: <input type="file" name="my_image" />
  4.  ...
  5.  </form>
PHP-Code:
  1.  // get data from form field 'my_image'
  2.  $id 'my_image';
  3.  // output to directory 'foo/bar/' using filename 'image'
  4.  // (extension will be determined automatically)
  5.  $file 'foo/bar/image';
  6.  // output as png image
  7.  $type 'png';
  8.  // limit upload to 150 kbyte
  9.  $size 150000;
  10.  // resize to 150px x 200px
  11.  $width 150;
  12.  $height 200;
  13.  // leave aspect-ratio untouched
  14.  $ratio true;
  15.  // set background color to gray
  16.  $color array(808080);
  17.  
  18.  // call method
  19.  $result Image::uploadFile($id$file$type$size$width$height$ratio$color);
  20.  
  21.  // check for errors
  22.  if (is_string($result)) {
  23.      print "The image was successfully uploaded to: ".$result;
  24.  else {
  25.      switch ($result)
  26.      {
  27.          case UPLOAD_ERR_SIZE:
  28.          case UPLOAD_ERR_INI_SIZE:
  29.          case UPLOAD_ERR_FORM_SIZE:
  30.              die"File too big!" );
  31.          break;
  32.          case UPLOAD_ERR_NO_FILE:
  33.              die"No file has been uploaded!" );
  34.          break;
  35.          case UPLOAD_ERR_INVALID_TARGET:
  36.              die"Unable to write to file: ".$file );
  37.          break;
  38.          case UPLOAD_ERR_FILE_TYPE:
  39.              die"The file is not a recognized image!" );
  40.          break;
  41.          default:
  42.              die"Some unexpected error occured!" );
  43.          break;
  44.      }
  45.  }
  • since: 2.8.9
  • access: public
inherited from base classes

Inherited From Object

Documentation generated on Sat, 03 Jan 2009 22:22:28 +0100 by phpDocumentor 1.4.0

yana author: Thomas MeyerHomepage: www.yanaframework.net