# Image Functions

## Introduction

PHP is not limited to creating just HTML output. It can also be used to create and manipulate image files in a variety of different image formats, including gif, png, jpg, wbmp, and xpm. Even more convenient, PHP can output image streams directly to a browser. You will need to compile PHP with the GD library of image functions for this to work. GD and PHP may also require other libraries, depending on which image formats you want to work with.

You can use the image functions in PHP to get the size of JPEG, GIF, PNG, SWF, TIFF and JPEG2000 images.

With the exif extension, you are able to work with information stored in headers of JPEG and TIFF images. This way you can read meta data generated by digital cameras. The exif functions do not require the GD library.

> Note: Read the requirements section about how to expand image capabilities to read, write and modify images. To read meta data of pictures taken by digital cameras you need the above mentioned exif extension.

## Requirements

If you have the GD library (available at » http://www.libgd.org/) you will also be able to create and manipulate images.

The format of images you are able to manipulate depend on the version of GD you install, and any other libraries GD might need to access those image formats. Versions of GD older than gd-1.6 support GIF format images, and do not support PNG, where versions greater than gd-1.6 and less than gd-2.0.28 support PNG, not GIF. GIF support was re-enabled in gd-2.0.28.

> Note: Since PHP 4.3 there is a bundled version of the GD lib. This bundled version has some additional features like alpha blending, and should be used in preference to the external library since its codebase is better maintained and more stable.

> Note: Support for GD 1.x has been removed as of PHP 6.0.0, which requires GD 2.0.33 or later.

You may wish to enhance GD to handle more image formats.

Supported image formats
Image format | Library to download | Notes
--- | --- | ---
gif |  | Only supported in GD versions older than gd-1.6 and newer than gd-2.0.28. Read-only GIF support is available with PHP 4.3.0 and the bundled GD-library. Write support is available since PHP 4.3.9 and PHP 5.0.1.
jpeg-6b | » ftp://ftp.uu.net/graphics/jpeg/ | When buliding the jpeg-v6b library (prior to building PHP) you must use the --enable-shared option in the configure step. If you do not, you will receive an error saying libjpeg.(a|so) not found when you get to the configure step of building PHP.
png | » http://www.libpng.org/pub/png/libpng.html | Only supported in GD versions greater than gd-1.6.
xpm | » ftp://metalab.unc.edu/pub/Linux/libs/X/!INDEX.html | It's likely you have this library already available, if your system has an installed X-Environment.

You may wish to enhance GD to deal with different fonts. The following font libraries are supported:

Supported font libraries
Font library | Download | Notes
--- | --- | ---
FreeType 1.x | » http://www.freetype.org/ | Support removed as of PHP 6.0.0
FreeType 2 | » http://www.freetype.org/ |
T1lib | » ftp://sunsite.unc.edu/pub/Linux/libs/graphics/) | Support for Postscript Type 1 fonts.

## Installation

To enable GD-support configure PHP --with-gd[=DIR], where DIR is the GD base install directory. To use the recommended bundled version of the GD library (which was first bundled in PHP 4.3.0), use the configure option --with-gd. GD library requires libpng and libjpeg to compile.

In Windows, you'll include the GD2 DLL php_gd2.dll as an extension in php.ini. The GD1 DLL php_gd.dll was removed in PHP 4.3.2. Also note that the preferred truecolor image functions, such as imagecreatetruecolor(), require GD2.

To disable GD support in PHP 3 add --without-gd to your configure line.

Enhance the capabilities of GD to handle more image formats by specifying the --with-XXXX configure switch to your PHP configure line.

Supported image formats
Image Format | Configure Switch
--- | ---
jpeg-6b | To enable support for jpeg-6b add --with-jpeg-dir=DIR.
png | To enable support for png add --with-png-dir=DIR. Note, libpng requires the zlib library, therefore add --with-zlib-dir[=DIR] to your configure line.
xpm | To enable support for xpm add --with-xpm-dir=DIR. If configure is not able to find the required libraries, you may add the path to your X11 libraries.

> Note: When compiling PHP with libpng, you must use the same version that was linked with the GD library.

Enhance the capabilities of GD to deal with different fonts by specifying the --with-XXXX configure switch to your PHP configure line.

Supported font libraries
Font library | Configure Switch
--- | ---
FreeType 1.x | To enable support for FreeType 1.x add --with-ttf[=DIR].
FreeType 2 | To enable support for FreeType 2 add --with-freetype-dir=DIR.
T1lib | To enable support for T1lib (Postscript Type 1 fonts) add --with-t1lib[=DIR].
Native TrueType string function | To enable support for native TrueType string function add --enable-gd-native-ttf.

## Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Image Configure Options
Name | Default | Changeable | Changelog
--- | --- | --- | ---
gd.jpeg_ignore_warning | "0" | PHP_INI_ALL | Available since PHP 5.1.3.

For further details and definitions of the PHP_INI_* constants, see the php.ini directives.

Here's a short explanation of the configuration directives.

`gd.jpeg_ignore_warning` bool

  Ignore warnings created by jpeg2wbmp() and imagecreatefromjpeg()

See also the exif configuration directives.

Warning

Image functions are very memory intensive. Be sure to set memory_limit high enough.

## Resource Types

This extension defines two resource types: an image identifier and a font identifier.

## Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

`GD_VERSION` (string)
  The GD version PHP was compiled against. (Available as of PHP 5.2.4)
`GD_MAJOR_VERSION` (integer)
  The GD major version PHP was compiled against. (Available as of PHP 5.2.4)
`GD_MINOR_VERSION` (integer)
  The GD minor version PHP was compiled against. (Available as of PHP 5.2.4)
`GD_RELEASE_VERSION` (integer)
  The GD release version PHP was compiled against. (Available as of PHP 5.2.4)
`GD_EXTRA_VERSION` (string)
  The GD "extra" version (beta/rc..) PHP was compiled against. (Available as of PHP 5.2.4)
`IMG_GIF` (integer)
  Used as a return value by imagetypes()
`IMG_JPG` (integer)
  Used as a return value by imagetypes()
`IMG_JPEG` (integer)
  Used as a return value by imagetypes()

  > Note: This constant has the same value as `IMAGE_JPG`

`IMG_PNG` (integer)
  Used as a return value by imagetypes()
`IMG_WBMP` (integer)
  Used as a return value by imagetypes()
`IMG_XPM` (integer)
  Used as a return value by imagetypes()
`IMG_COLOR_TILED` (integer)
  Special color option which can be used in stead of color allocated with imagecolorallocate() or imagecolorallocatealpha()
`IMG_COLOR_STYLED` (integer)
  Special color option which can be used in stead of color allocated with imagecolorallocate() or imagecolorallocatealpha()
`IMG_COLOR_BRUSHED` (integer)
  Special color option which can be used in stead of color allocated with imagecolorallocate() or imagecolorallocatealpha()
`IMG_COLOR_STYLEDBRUSHED` (integer)
  Special color option which can be used in stead of color allocated with imagecolorallocate() or imagecolorallocatealpha()
`IMG_COLOR_TRANSPARENT` (integer)
  Special color option which can be used in stead of color allocated with imagecolorallocate() or imagecolorallocatealpha()
`IMG_ARC_ROUNDED` (integer)
  A style constant used by the imagefilledarc() function.

  > Note: This constant has the same value as `IMG_ARC_PIE`

`IMG_ARC_PIE` (integer)
  A style constant used by the imagefilledarc() function.
`IMG_ARC_CHORD` (integer)
  A style constant used by the imagefilledarc() function.
`IMG_ARC_NOFILL` (integer)
  A style constant used by the imagefilledarc() function.
`IMG_ARC_EDGED` (integer)
  A style constant used by the imagefilledarc() function.
`IMG_GD2_RAW` (integer)
  A type constant used by the imagegd2() function.
`IMG_GD2_COMPRESSED` (integer)
  A type constant used by the imagegd2() function.
`IMG_EFFECT_REPLACE` (integer)
  Alpha blending effect used by the imagelayereffect() function.
`IMG_EFFECT_ALPHABLEND` (integer)
  Alpha blending effect used by the imagelayereffect() function.
`IMG_EFFECT_NORMAL` (integer)
  Alpha blending effect used by the imagelayereffect() function.
`IMG_EFFECT_OVERLAY` (integer)
  Alpha blending effect used by the imagelayereffect() function.
`IMG_FILTER_NEGATE` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_GRAYSCALE` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_BRIGHTNESS` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_CONTRAST` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_COLORIZE` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_EDGEDETECT` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_GAUSSIAN_BLUR` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_SELECTIVE_BLUR` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_EMBOSS` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_MEAN_REMOVAL` (integer)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_SMOOTH` (integer)
  Special GD filter used by the imagefilter() function.
`IMAGETYPE_GIF` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JPEG` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_PNG` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_SWF` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_PSD` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_BMP` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_WBMP` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_XBM` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_TIFF_II` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_TIFF_MM` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_IFF` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JB2` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JPC` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JP2` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JPX` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_SWC` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_ICO` (integer)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions. (Available as of PHP 5.3.0)
`PNG_NO_FILTER` (integer)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_NONE` (integer)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_SUB` (integer)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_UP` (integer)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_AVG` (integer)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_PAETH` (integer)
  A special PNG filter, used by the imagepng() function.
`PNG_ALL_FILTERS` (integer)
  A special PNG filter, used by the imagepng() function.

## Examples

Example#1 PNG creation with PHP

`<?php
header("Content-type: image/png");
$string = $_GET['text'];
$im = imagecreatefrompng("images/button1.png");
$orange = imagecolorallocate($im, 220, 210, 60);
$px = (imagesx($im) - 7.5 * strlen($string)) / 2;
imagestring($im, 3, $px, 9, $string, $orange);
imagepng($im);
imagedestroy($im);
?>`
This example would be called from a page with a tag like: <img src="button.php?text=text">. The above button.php script then takes this "text" string and overlays it on top of a base image which in this case is "images/button1.png" and outputs the resulting image. This is a very convenient way to avoid having to draw new button images every time you want to change the text of a button. With this method they are dynamically generated.

## Table of Contents

- gd_info — Retrieve information about the currently installed GD library
- getimagesize — Get the size of an image
- image_type_to_extension — Get file extension for image type
- image_type_to_mime_type — Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- image2wbmp — Output image to browser or file
- imagealphablending — Set the blending mode for an image
- imageantialias — Should antialias functions be used or not
- imagearc — Draws an arc
- imagechar — Draw a character horizontally
- imagecharup — Draw a character vertically
- imagecolorallocate — Allocate a color for an image
- imagecolorallocatealpha — Allocate a color for an image
- imagecolorat — Get the index of the color of a pixel
- imagecolorclosest — Get the index of the closest color to the specified color
- imagecolorclosestalpha — Get the index of the closest color to the specified color + alpha
- imagecolorclosesthwb — Get the index of the color which has the hue, white and blackness nearest to the given color
- imagecolordeallocate — De-allocate a color for an image
- imagecolorexact — Get the index of the specified color
- imagecolorexactalpha — Get the index of the specified color + alpha
- imagecolormatch — Makes the colors of the palette version of an image more closely match the true color version
- imagecolorresolve — Get the index of the specified color or its closest possible alternative
- imagecolorresolvealpha — Get the index of the specified color + alpha or its closest possible alternative
- imagecolorset — Set the color for the specified palette index
- imagecolorsforindex — Get the colors for an index
- imagecolorstotal — Find out the number of colors in an image's palette
- imagecolortransparent — Define a color as transparent
- imageconvolution — Apply a 3x3 convolution matrix, using coefficient and offset
- imagecopy — Copy part of an image
- imagecopymerge — Copy and merge part of an image
- imagecopymergegray — Copy and merge part of an image with gray scale
- imagecopyresampled — Copy and resize part of an image with resampling
- imagecopyresized — Copy and resize part of an image
- imagecreate — Create a new palette based image
- imagecreatefromgd2 — Create a new image from GD2 file or URL
- imagecreatefromgd2part — Create a new image from a given part of GD2 file or URL
- imagecreatefromgd — Create a new image from GD file or URL
- imagecreatefromgif — Create a new image from file or URL
- imagecreatefromjpeg — Create a new image from file or URL
- imagecreatefrompng — Create a new image from file or URL
- imagecreatefromstring — Create a new image from the image stream in the string
- imagecreatefromwbmp — Create a new image from file or URL
- imagecreatefromxbm — Create a new image from file or URL
- imagecreatefromxpm — Create a new image from file or URL
- imagecreatetruecolor — Create a new true color image
- imagedashedline — Draw a dashed line
- imagedestroy — Destroy an image
- imageellipse — Draw an ellipse
- imagefill — Flood fill
- imagefilledarc — Draw a partial ellipse and fill it
- imagefilledellipse — Draw a filled ellipse
- imagefilledpolygon — Draw a filled polygon
- imagefilledrectangle — Draw a filled rectangle
- imagefilltoborder — Flood fill to specific color
- imagefilter — Applies a filter to an image
- imagefontheight — Get font height
- imagefontwidth — Get font width
- imageftbbox — Give the bounding box of a text using fonts via freetype2
- imagefttext — Write text to the image using fonts using FreeType 2
- imagegammacorrect — Apply a gamma correction to a GD image
- imagegd2 — Output GD2 image to browser or file
- imagegd — Output GD image to browser or file
- imagegif — Output image to browser or file
- imagegrabscreen — Captures the whole screen
- imagegrabwindow — Captures a window
- imageinterlace — Enable or disable interlace
- imageistruecolor — Finds whether an image is a truecolor image
- imagejpeg — Output image to browser or file
- imagelayereffect — Set the alpha blending flag to use the bundled libgd layering effects
- imageline — Draw a line
- imageloadfont — Load a new font
- imagepalettecopy — Copy the palette from one image to another
- imagepng — Output a PNG image to either the browser or a file
- imagepolygon — Draws a polygon
- imagepsbbox — Give the bounding box of a text rectangle using PostScript Type1 fonts
- imagepsencodefont — Change the character encoding vector of a font
- imagepsextendfont — Extend or condense a font
- imagepsfreefont — Free memory used by a PostScript Type 1 font
- imagepsloadfont — Load a PostScript Type 1 font from file
- imagepsslantfont — Slant a font
- imagepstext — Draws a text over an image using PostScript Type1 fonts
- imagerectangle — Draw a rectangle
- imagerotate — Rotate an image with a given angle
- imagesavealpha — Set the flag to save full alpha channel information (as opposed to single-color transparency) when saving PNG images
- imagesetbrush — Set the brush image for line drawing
- imagesetpixel — Set a single pixel
- imagesetstyle — Set the style for line drawing
- imagesetthickness — Set the thickness for line drawing
- imagesettile — Set the tile image for filling
- imagestring — Draw a string horizontally
- imagestringup — Draw a string vertically
- imagesx — Get image width
- imagesy — Get image height
- imagetruecolortopalette — Convert a true color image to a palette image
- imagettfbbox — Give the bounding box of a text using TrueType fonts
- imagettftext — Write text to the image using TrueType fonts
- imagetypes — Return the image types supported by this PHP build
- imagewbmp — Output image to browser or file
- imagexbm — Output XBM image to browser or file
- iptcembed — Embed binary IPTC data into a JPEG image
- iptcparse — Parse a binary IPTC block into single tags.
- jpeg2wbmp — Convert JPEG image file to WBMP image file
- png2wbmp — Convert PNG image file to WBMP image file