PHPlot supports both built-in GD fonts and TrueType fonts (if available on your system). TrueType fonts generally produce higher quality text, but using them requires more internal computations. The built-in GD fonts are faster to render, but are limited to one typeface and 5 available sizes. TrueType fonts can be drawn at any size and angle, and many typefaces are available. On most systems, TrueType fonts are anti-aliased for improved appearance, but under some conditions the GD fonts may be easier to read. TrueType fonts support much wider character sets, including special symbols, while the GD fonts are more limited.

The following figure shows the built-in GD fonts plus a sample TrueType font. (Depending on how you are viewing this manual, the sizes of the fonts in this figure might differ from how they would look in a PHPlot image. For more on font sizes, see the notes with SetFont.)

Each type of text available in PHPlot has an element name. When selecting text fonts with SetFont and related functions, you use the element name to indicate what type of text you are configuring. The following table lists the PHPlot text element names.

Notes: generic is also used for text drawn from a callback when no font is specified. See Section 4.4.5, “Using Callbacks to Annotate Plots” and DrawText. Although generic is used for error image text, changing the font or size has no effect because the error handler resets the font to the default before displaying the error. Message image text refers to DrawMessage.

PHPlot text can use built-in GD fonts or TrueType fonts. When using GD fonts, you specify a font name as a number between 1 and 5. This selects from 5 built-in GD fonts. When using TrueType fonts, you need to specify a font filename. The rest of this section discusses only TrueType fonts.

On Windows systems, you need to use the font filename, not the font name. You can get the font filename using Control Panel - Fonts. For example, Windows applications may display "Arial Black", or "Arial Black (TrueType)" as a font name, but the actual font filename is "ariblk.ttf". Since GD knows to look for fonts in the Windows font directory, you will not need to specify a full pathname to font files, unless the font is installed in some other directory.

On Windows, you can use the "Character Map" system tool to examine a font. This can also be used to find the Unicode character code of a special character. These will be displayed in hexadecimal, for example U+20AC for the Euro. See Section 3.8.5, “Using Extended Characters” for more information on using special characters.

Here are some font selection examples for Windows:

# For titles, use Arial Bold Italic at 14 points:
$plot->SetFontTTF('title', 'ARIALBI.TTF', 14)
# For X Title, use Verdana at 12 points:
$plot->SetFontTTF('x_title', 'VERDANA.TTF', 12)

On some Linux and similar systems, GD is able to find fonts specified without paths, but on other systems you will have to specify a font directory with either SetTTFPath or as part of the font name in SetFontTTF. If you specify a full pathname to a font, you must also supply the extension (.ttf); you may omit the extension when relying on GD to find the font. Remember that font filenames are case sensitive on most of these systems.

The font search path for GD (bundled with PHP) includes the following directories on Linux and similar systems:

If your system has TrueType fonts in one of those directories, you can select them with a filename only. If not, you must use a full directory path in either the font name or with SetTTFPath.

Your Linux system may include a tool for examining fonts. One such tool is gucharmap. This can also be used to find the Unicode character code of a special character. These may be displayed in hexadecimal, for example U+20AC for the Euro. See the next section for more information on using special characters.

Here are some font selection examples for Linux:

# On systems with fonts in an expected place, like Slackware Linux,
# just use the font filename:
# For titles, use Liberation Sans Bold Italic at 14 points:
$plot->SetFontTTF('title', 'LiberationSans-BoldItalic.ttf', 14)
# For X Title, use DejaVuSans Bold at 12 points:
$plot->SetFontTTF('x_title', 'DejaVuSans-Bold.ttf', 12)

# Ubuntu and Debian use subdirectories under a searched path.
# You can use a partial path here.
$plot->SetFontTTF('x_title', 'liberation/LiberationSans-Regular.ttf', 12)
# Note: Older Ubuntu/Debian used the path ttf-liberation/...

# Fedora uses subdirectories which are not under a searched path.
# You must use full paths here.
$plot->SetTTFPath('/usr/share/fonts/liberation/');
$plot->SetFontTTF('x_title', 'LiberationSans-Regular.ttf', 12)

If you try to use TrueType text without specifying a font name, PHPlot will use the default font. You can set the default font with SetDefaultTTFont. If you do not set a default font, PHPlot tries to locate a sans-serif font to use. Here are the font names that PHPlot tries in order. First it tries the filename alone, letting GD use its search path, and then it tries with the default font path, as set with SetTTFPath.

The last item on the list is used regardless of whether it can be found or not. This means if you enable TrueType fonts without setting a default, and get a fatal error from PHPlot that it can't find the font benjamingothic.ttf, this means PHPlot was unable to find any of the standard fonts in its list. On that system, then, you must provide either a font directory, or use full font pathnames.

You can include non-ASCII characters in your PHPlot labels and titles. This includes characters from languages other than English, accented characters, and special symbols.

PHPlot itself does not do any special processing of text strings, so you should refer to the PHP GD and Image Functions reference for more information, in particular imagettftext().

To use extended characters in your PHPlot text strings, you need a TrueType font that contains the characters you want. Ideally, you want a Unicode font. You might have to examine the font using an operating system-specific tool to see if your characters are present and to find their numeric values.

There are three basic ways to include extended characters in your text strings. The examples below use the Euro character, which is decimal Unicode value 8364.

The first two of these options are shown in the example below, both of which set the Y axis title to "Items per €100".

$plot->SetYTitle("Items per €100"); # Numeric character entity
$plot->SetYTitle("Items per \xe2\x82\xac100"); # UTF-8 encoding

You can also use PHP functions to encode your characters for including in PHPlot text strings. See the PHP documentation for the functions html_entity_decode() and iconv(). Here are some examples (sent in by SourceForge user 'kalvaro'):

# Encode the Euro symbol into UTF-8:
$chars = html_entity_decode('€', ENT_NOQUOTES, 'UTF-8');

# Use iconv() to convert a character value xA4 in ISO-8859-15 to UTF:
$chars = iconv('iso-8859-15', 'utf-8', chr(0xA4));