PEAR is archived and read-only

This mirror preserves historical PEAR package releases and metadata so existing references remain available.

Home » Images » Image_Text » Manual

Class Summary Image_Text

Class Summary Image_Text – Image_Text - Advanced text manipulations in images

Image_Text - Advanced text manipulations in images

Image_Text provides advanced text manipulation facilities for GD2 image generation with PHP. Simply add text clippings to your images, let the class automatically determine lines, rotate text boxes around their center or top left corner. These are only a couple of features Image_Text provides.

Class Trees for Image_Text

constructor Image_Text::Image_Text

constructor Image_Text::Image_Text() – Constructor

Synopsis

require_once 'ImageText.php';

void constructor Image_Text::Image_Text ( string $text , array $options = null )

Description

Set the text and options. This initializes a new Image_Text object. You must set your text here. Optinally you can set all options here using the $options parameter. If you finished switching all options you have to call the init() method first befor doing anything further! See Image_Text::set() for further information.

Parameter

string $text

Text to print.

array $options

Options.

Throws

throws no exceptions thrown

See

see Image_Text::set(), Image_Text::init()

Note

This function can not be called statically.

Image_Text::autoMeasurize

Image_Text::autoMeasurize() – Auto measurize text

Synopsis

require_once 'ImageText.php';

int Image_Text::autoMeasurize ( int $start = false , int $end = false )

Description

Automatically determines the greatest possible font size to fit the text into the text box. This method may be very resource intensive on your webserver. A good tweaking point are the $start and $end parameters, which specify the range of font sizes to search through. Anyway, the results should be cached if possible. You can optionally set $start and $end here as a parameter or the settings of the options array are used.

Parameter

integer $start

Fontsize to start testing with.

integer $end

Fontsize to end testing with.

Return value

returns Fontsize measured or PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::measurize()

Note

This function can not be called statically.

Image_Text::display

Image_Text::display() – Display the image (send it to the browser).

Synopsis

require_once 'ImageText.php';

bool Image_Text::display ( bool $save = false , bool $free = false )

Description

This will output the image to the users browser. You can use the standard IMAGETYPE_* constants to determine which image type will be generated. Optionally you can save your image to a destination you set in the options.

Parameter

boolean $save

Save or not the image on printout.

boolean $free

Free the image on exit.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::save()

Note

This function can not be called statically.

Image_Text::getImg

Image_Text::getImg() – Return the image ressource.

Synopsis

require_once 'ImageText.php';

resource& Image_Text::getImg ( )

Description

Get the image canvas.

Return value

returns Used image resource

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Image_Text::init

Image_Text::init() – Initialiaze the Image_Text object.

Synopsis

require_once 'ImageText.php';

bool Image_Text::init ( )

Description

This method has to be called after setting the options for your Image_Text object. It initializes the canvas, normalizes some data and checks important options. Be shure to check the initialization after you switched some options. The set() method may force you to reinitialize the object.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::set()

Note

This function can not be called statically.

Image_Text::measurize

Image_Text::measurize() – Measurize text into the text box

Synopsis

require_once 'ImageText.php';

array Image_Text::measurize ( bool $force = false )

Description

This method makes your text fit into the defined textbox by measurizing the lines for your given font-size. You can do this manually before rendering (or use even Image_Text::autoMeasurize()) or the renderer will do measurizing automatically.

Parameter

boolean $force

Optionally, default is FALSE, set TRUE to force measurizing.

Return value

returns Array of measured lines or PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::autoMeasurize()

Note

This function can not be called statically.

Image_Text::render

Image_Text::render() – Render the text in the canvas using the given options.

Synopsis

require_once 'ImageText.php';

bool Image_Text::render ( bool $force = false )

Description

This renders the measurized text or automatically measures it first. The $force parameter can be used to switch of measurizing problems (this may cause your text being rendered outside a given text box or destroy your image completely).

Parameter

boolean $force

Optional, initially FALSE, set TRUE to silence measurize errors.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Image_Text::save

Image_Text::save() – Save image canvas.

Synopsis

require_once 'ImageText.php';

bool Image_Text::save ( string $destFile = false )

Description

Saves the image to a given destination. You can leave out the destination file path, if you have the option for that set correctly. Saving is possible with the save() method, too.

Parameter

string $destFile

The destination to save to (optional, uses options value else).

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::display()

Note

This function can not be called statically.

Image_Text::set

Image_Text::set() – Set options

Synopsis

require_once 'ImageText.php';

bool Image_Text::set ( mixed $option , mixed $value = null )

Description

Set a single or multiple options. It may happen that you have to reinitialize the Image_Text object after changing options.

Possible options to set
Option Description
x

This sets the top left coordinates (using x/y) or the center point coordinates (using cx/cy) for your text box. The values from cx/cy will overwrite x/y.
y
cx
cy
canvas

You can set different values as a canvas:

  • A gd image resource.
  • An array with 'width' and 'height'.
  • Nothing (the canvas will be measured after the real text size).
antialias

This is usually true. Set it to false to switch antialiasing off.
width

The width and height for your text box.
height
halign

Alignment of your text inside the textbox. Use alignment constants to define vertical and horizontal alignment.
valign
angle

The angle to rotate your text box.
color

An array of color values. Colors will be rotated in the mode you choose (linewise or paragraphwise). Can be in the following formats:

  • String representing HTML style hex couples (+ unusual alpha couple in the first place, optional).
  • Array of int values using 'r', 'g', 'b' and optionally 'a' as keys.
color_mode

The color rotation mode for your color sets. Does only apply if you defined multiple colors. Use 'line' or 'paragraph'.
background_color

Defines the background color. Use NULL if you would like to have the background transparent. Default is #000000.
enable_alpha

If the alpha channel should be enabled. Automatically enabled when background_color is set to NULL. Default is FALSE.
font_path

Location of the font to use.
font_file
font_size

The font size to render text in (will be overwriten if you use automeasurize).
line_spacing

Measure for the line spacing to use. Default is 0.5.
min_font_size

Automeasurize settings. Try to keep this area as small as possible to get better performance.
max_font_size
max_lines

The maximum number of lines to render. Default is 100.
image_type

The type of image (use image type constants). Is default set to PNG.
dest_file

The destination to (optionally) save your file.

Parameter

mixed $option

A single option name or the options array.

mixed $value

Option value if $option is string.

Return value

returns True on success, otherwise PEAR_Error.

Throws

throws no exceptions thrown

See

see Image_Text::Image_Text()

Note

This function can not be called statically.

Image_Text::setColor

Image_Text::setColor() – Set a color

Synopsis

require_once 'ImageText.php';

bool Image_Text::setColor ( mixed $color , mixed $id = 0 )

Description

This method is used to set a color at a specific color ID inside the color cycle.

The following colors syntaxes are understood by this method:

Parameter

mixed $color

Color value.

mixed $id

ID (in the color array) to set color to.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::setColors(), Image_Text::set()

Note

This function can not be called statically.

Image_Text::setColors

Image_Text::setColors() – Set the color-set

Synopsis

require_once 'ImageText.php';

bool Image_Text::setColors ( mixed $colors )

Description

Using this method you can set multiple colors for your text. Use a simple numeric array to determine their order and give it to this function. Multiple colors will be cycled by the options specified 'color_mode' option. The given array will overwrite the existing color settings!

The following colors syntaxes are understood by this method:

A single color or an array of colors are allowed here.

Parameter

mixed $colors

Single color or array of colors.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::setColor(), Image_Text::set()

Note

This function can not be called statically.

Package Image_Text Constants

Package Image_Text Constants – Constants defined in and used by Image_Text

All Constants

Constants defined in ImageText.php

Name Value Line Number
IMAGE_TEXT_ALIGN_BOTTOM "bottom",true 56
IMAGE_TEXT_ALIGN_CENTER "center",true 43
IMAGE_TEXT_ALIGN_JUSTIFY "justify",true 61
IMAGE_TEXT_ALIGN_LEFT "left",true 35
IMAGE_TEXT_ALIGN_MIDDLE "middle",true 52
IMAGE_TEXT_ALIGN_RIGHT "right",true 39
IMAGE_TEXT_ALIGN_TOP "top",true 48
IMAGE_TEXT_REGEX_HTMLCOLOR ,true"/^/^[#|]([a-f0-9]{2})?([a-f0-9]{2})([a-f0-9]{2})([a-f0-9]{2})$/i" 30