PHP CookBook

Recipe 15.5 Drawing Text

15.5.1 Problem

You want to draw text as a graphic. This allows you to make dynamic buttons or hit counters.

15.5.2 Solution

For built-in GD fonts, use ImageString( ):

ImageString($image, 1, $x, $y, 'I love PHP Cookbook', $text_color);

For TrueType fonts, use ImageTTFText( ):

ImageTTFText($image, $size, 0, $x, $y, $text_color, '/path/to/font.ttf', 
             'I love PHP Cookbook');

For PostScript Type 1 fonts, use ImagePSLoadFont( ) and ImagePSText( ):

$font = ImagePSLoadFont('/path/to/font.pfb');
ImageString($image, 'I love PHP Cookbook', $font, $size, 
            $text_color, $background_color, $x, $y);

15.5.3 Discussion

Call ImageString( ) to place text onto the canvas. Like other GD drawing functions, ImageString( ) needs many inputs: the image to draw on, the font number, the x and y coordinates of the upper right position of the first characters, the text string to display, and finally, the color to use to draw the string.

With ImageString( ), there are five possible font choices, from 1 to 5. Font number 1 is the smallest, while font 5 is the largest, as shown in Figure 15-5. Anything above or below that range generates a size equivalent to the closest legal number.

Figure 15-5. Built-in GD font sizes

To draw text vertically instead of horizontally, use the function ImageStringUp( ) instead. Figure 15-6 shows the output.

ImageStringUp($image, 1, $x, $y, 'I love PHP Cookbook', $text_color);

Figure 15-6. Vertical text

To use TrueType fonts, you must also install the FreeType library and configure PHP during installation to use FreeType. The FreeType main site is http://www.freetype.org. To enable FreeType 1.x support, use --with-ttf and for FreeType 2.x, pass --with-freetype-dir=DIR.

Like ImageString( ), ImageTTFText( ) prints a string to a canvas, but it takes slightly different options and needs them in a different order:

ImageTTFText($image, $size, $angle, $x, $y, $text_color, '/path/to/font.ttf', 
             $text);

The $size argument is the font size in pixels; $angle is an angle of rotation, in degrees going counter-clockwise; and /path/to/font.ttf is the pathname to TrueType font file. Unlike ImageString( ), ($x,$y) are the lower left coordinates of the baseline for the first character. (The baseline is where the bottom of most characters sit. Characters such as "g" and "j" extend below the baseline; "a" and "z" sit on the baseline.)

PostScript Type 1 fonts require t1lib to be installed. It can be downloaded from ftp://sunsite.unc.edu/pub/Linux/libs/graphics/ and built into PHP using --with-t1lib.

Again, the syntax for printing text is similar but not the same:

$font = ImagePSLoadFont('/path/to/font.pfb');
ImagePSText($image, $text, $font, $size, $text_color, $background_color, $x, $y);
ImagePSFreeFont($font);

First, PostScript font names can't be directly passed into ImagePSText( ). Instead, they must be loaded using ImagePSLoadFont( ). On success, the function returns a font resource usable with ImagePSText( ). In addition, besides specifying a text color, you also pass a background color to be used in antialiasing calculations. The ($x,$y) positioning is akin to the how the TrueType library does it. Last, when you're done with a font, you can release it from memory by calling ImagePSFreeFont( ).

Besides the mandatory arguments listed above, ImagePSText( ) also accepts four optional ones, in this order: space , tightness, angle, and antialias_steps. You must include all four or none of the four (i.e., you can't pass one, two, or three of these arguments). The first controls the size of a physical space (i.e., what's generated by hitting the space bar); the second is the tightness of the distance between letters; the third is a rotation angle, in degrees, counter-clockwise; and the last is an antialiasing value. This number must be either 4 or 16. For better looking, but more computationally expensive graphics, use 16 instead of 4.

By default, space, tightness, and angle are all 0. A positive number adds more space between words and letters or rotates the graphic counterclockwise. A negative number kerns words and letters or rotates in the opposite direction. The following example has the output shown in Figure 15-7:

// normal image
ImagePSText($image, $text, $font, $size, $black, $white, $x, $y,
            0, 0, 0, 4);

// extra space between words
ImagePSText($image, $text, $font, $size, $black, $white, $x, $y + 30, 
            100, 0, 0, 4);

// extra space between letters
ImagePSText($image, $text, $font, $size, $black, $white, $x, $y + 60, 
            0, 100, 0, 4);

Figure 15-7. Words with extra space and tightness

15.5.4 See Also

Recipe 15.6 for drawing centered text; documentation on ImageString( ) at http://www.php.net/imagestring, ImageStringUp( ) at http://www.php.net/imagestringup, ImageTTFText( ) at http://www.php.net/imagettftext, ImagePSText( ) at http://www.php.net/imagepstext, and ImagePSLoadFont( ) at http://www.php.net/imagepsloadfont.