Section 16.6. Outputting Text

16.6. Outputting Text

To output text using PHP, you first need fonts. PHP allows you to use TrueType (TTF) fonts, PostScript Type 1 (PS) fonts, or FreeType 2 fonts, with TTF tending to be the most popular, due to the availability of fonts. If you are running Windows, you probably have at least 20 TTF fonts already installed that you can usecheck in the "Fonts" subdirectory of your Windows directory to see what is available. Many Unix distributions come with TTF fonts installed alsoeither check in /usr/share/fonts/truetype, or run a search for them. Alternatively, if you have a Windows CD around, you can borrow some from there. Some distributions (including Debian and SUSE) allow you to install Microsoft's Core Fonts for the Web. The Free Software Foundation has a set of free fonts that you can grab from its web site.

For this next example, I used the font Arial, which is stored in the same directory as my PHP script. Save this code as addingtext.php:

     $image = imagecreate(400,300);     $blue = imagecolorallocate($image, 0, 0, 255);     $white = ImageColorAllocate($image, 255,255,255);     if(!isset($_GET['size'])) $_GET['size'] = 44;     if(!isset($_GET['text'])) $_GET['text'] = "Hello, world!";     imagettftext($image, $_GET['size'], 15, 50, 200, $white,             "ARIAL", $_GET['text']);     header("content-type: image/png");     imagepng($image);     imagedestroy($image); 

The two isset( ) lines in that example are there to make sure there is a default font size, 44, and default text, "Hello, world!" for our image. These are set only if you do not pass values using addingtext.php?size=26&text=Foobarbaz.

Next comes the important function, imagettftext( ), which takes eight parameters in total: the image resource to draw on, font size to use, angle to draw at, X coordinate, Y coordinate, color, font file, and the text to write. A few of those parameters are the same as parameters we've used in other functions, but font size in points, angle, name of font, and the text to print are all new. The X and Y coordinates might fool you at first, because they should be set to the position in which you want the lower-left corner of the first character to appear.

The angle parameter works almost in the same manner as the angle parameters used in imagefilledarc( ), with the difference being that it works in the opposite directionthe angles in imagefilledarc( ) work in a clockwise direction from 3 o'clock, whereas imagettftext( ) works counter-clockwise. That is, specifying 15 as the angle will make the text rotate 15 degrees so that it slants upward.

The font name parameter needs to point to the TTF file you want to use. If this filename does not begin with /, PHP will automatically add .ttf to the end and search locally. On Unix machines, you may find that PHP searches in /usr/share/fonts/truetype. As you can see in the example, "ARIAL" is specified, so ARIAL.TTF will be loaded and used for printing the text.

The final parameter for the function is the text to print, and you should be sure to specify any new lines as \n\r, not one or the other. You may find that certain fonts do not have various special charactersin this situation, you will see empty boxes drawn rather than the special characters.

The output from this script is shown in Figure 16-6.

Figure 16-6. Any TrueType font at any size, any angle, and any colorall through one easy function

If you do not want your text to be anti-aliased (smooth-edged), put a minus sign before your color, e.g., -$white.

Fitting text into an exact space is a complex art, particularly when you rotate the text too. PHP makes the job easier with the function imagettfbbox( ), which will return an array containing the coordinates of a bounding box around the textliterally, how big it is in each of its dimensions. The complication here is that it is tricky to get the coordinate system right, as the numbers returned seem easier to use than they actually are.

To call imagettfbbox( ), you need to pass in four parameters: font point size, rotation angle, font name, and text string to measure. This is essentially a cut-down version of imagettftext( ), so you can just copy your existing call to that and remove the unnecessary parameters.

What you will get back is an array of eight elements, which are shown in Table 16-1.

Table 16-1. The eight elements in the array returned by imagettfbox( )

0	Lower-left corner, X coordinate
1	Lower-left corner, Y coordinate
2	Lower-right corner, X coordinate
3	Lower-right corner, Y coordinate
4	Upper-right corner, X coordinate
5	Upper-right corner, Y coordinate
6	Upper-left corner, X coordinate
7	Upper-left corner, Y coordinate

Each of those coordinates are relative to the text itself, viewed horizontally. That is, although 0 should be the lower-left corner of our first letter, it's unlikely that either the lower-left X or the lower-left Y will be 0, particularly if your text is rotated. For example, in our previous example we rotated text 15 degrees counter-clockwise, which would put the lower-left corner of our rotated text to the right and above the lower-left corner of the horizontal text. Add to that the fact that the numbers are frequently a little off, especially if you use large fonts, and you should be ready for problems!

However, if you are not rotating your text, or if you are rotating only a little (under about 20 degrees), you are not likely to encounter any problems, and you can use a fairly simple script like this next one to get your image fitting your text closely:

     if(!isset($_GET['size'])) $_GET['size'] = 44;     if(!isset($_GET['text'])) $_GET['text'] = "Hello, world!";     $size = imagettfbbox($_GET['size'], 0, "ARIAL", $_GET['text']);     $xsize = abs($size[0]) + abs($size[2]);     $ysize = abs($size[5]) + abs($size[1]);     $image = imagecreate($xsize, $ysize);     $blue = imagecolorallocate($image, 0, 0, 255);     $white = ImageColorAllocate($image, 255,255,255);     imagettftext($image, $_GET['size'], 0, abs($size[0]), abs($size[5]), $white,             "ARIAL", $_GET['text']);     header("content-type: image/png");     imagepng($image);     imagedestroy($image); 

Note the use of the abs( ) function to convert negative numbers to positive. The value abs($size['5']) is used as the Y coordinate for the text because imagettfbbox( ) returns its values from the lower-left corner of the baseline of the text string, not the absolute lower-left corner. The baseline of a letter is where it would sit if you were handwriting it on lined paperfor example, the letter "a" sits on the line, whereas the letter "y" sits below the line, with the "v" part of the letter resting on the baseline. The baseline problem is illustrated in Figures 16-7 and 16-8.

Figure 16-7. This text uses the image height to align the text to the bottom of the picture; note how the "g" in "sitting" is cut off because it falls below the baseline

Figure 16-8. This text aligns to the top of the picture, as our code does, so that the baseline is no longer right at the bottom and the "g" is fully visible