3.2. Necessary system requirements for the library

In order to run the JpGraph library there are some prerequisites that must be fulfilled. The PHP installation must have the low level graphic primitive library "GD" enabled and if TTF fonts shall work in the graphs the FreeType 2.x library must be enabled and installed in the PHP setup. Most modern PHP systems (since at least 2006) usually have these extensions enabled and installed by default which means it is usually rather simple to get the library working.

However, there are many systems out there and some older non-standard systems will require some manual intervention to work correctly.

Caution

One more time; The library is not guaranteed to run on a 64Bit OS. We will point out this several more time during this manual.

3.2.1. Verifying the PHP/GD installation

The first and most important step is to make sure that your PHP installations has the GD library enabled. The easiest way to find out if this has been enabled or not is to create a one line PHP program that has only one instruction, phpinfo()

1
<?php phpinfo(); ?>

Store this basic program as phpinfo.php in the document root. Then point the browser to

http://localhost/phpinfo.php

If the steps above was followed the browser should now show a lot of information about the PHP installation. In order to find out if the GD have been installed and enabled look for the GD section in the output. The figure below shows a typical output of this section

Figure 3.2. phphinfo() GD-Information

phphinfo() GD-Information


There are three important points to notice here.

  1. The GD Version. It should be 2.0.x. The GD version has been shipped with PHP for the last four years so this should not really be a problem. If for some odd reason the system only have GD 1.x installed then JpGraph 2.x, and 3.x cannot be used but it is still possible to use JpGraph 1.x.

    In addition the "bundled" version of GD should be used. This version is maintained together with PHP and is usually much more up to date then the stand alone GD version.

  2. FreeType version. This is required in order to use TTF fonts. This should be at least version 2.3.x Previous versions of the FreeType library have had known issues which has caused issues when used together with JpGraph.

  3. The final point worth checking is what type of image encoding the installation supports. The most common formats are PNG and JPEG. By default the library uses the PNG encoding format so it is important to check that the line that says "PNG Support" has "enabled" as value. As a rule of thumb PNG usually gives the smallest sizes of graph (best compression) so this is the recommended format. The only exception to this rule might be if a photo is used as background in the graph. Then it is possible that JPEG encoding gives a better compression since this is a destructive format (while PNG is a lossless format).

    For legacy reason it is also possible to use GIF encoding if the server supports this but if PNG is installed there are no good technical reasons to use GIF compression format. (The only possible usage of GIF is the ability to create an animated image by concatenating a number of GIF images which are then displayed in sequence. This is not possible with the (old) PNG standard.)

In order to remove any remaining doubts that the installation works as intended the following PHP script that only uses the GD library primitives should be run. This allows troubleshooting the installation without involving the additional complexity of JpGraph to make sure that the basics are in place.

Store the script in Example 3.1 your document root as "checkgd.php"

Example 3.1. Verifying the GD installations (checkgd.php)

1
2
3
4
5
6
7
8
9
10
11
<?php // content="text/plain; charset=utf-8"
$im = @imagecreate (200, 100) or die ( "cannot create a new gd image.");
$background_color = imagecolorallocate ($im, 240, 240, 240);
$border_color = imagecolorallocate ($im, 50, 50, 50);
$text_color = imagecolorallocate ($im, 233, 14, 91);
 
imagerectangle($im,0,0,199,99,$border_color);
imagestring ($im, 5, 10, 40, "a simple text string", $text_color );
header ("content-type: image/png");
imagepng ($im);
?>

Figure 3.3. Verifying the GD installations (checkgd.php)

Verifying the GD installations (checkgd.php)

Now point the browser to this file and fetch the script. This should show an image in the browser with the text "a simple text string" similar to what is shown in Figure 3.3

In order to be really sure that the GD 2.x version of the GD library is installed (as opposed to just GD 1.x) we need to use a slightly more advanced script that makes use of some features available in GD 2.x but not in GD 1.x. The largest difference is the support for TrueColor images in GD 2.x so we create a script that makes use of a truecolor canvas..

Example 3.2. Verifying GD2 (checkgd2.php)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<?php // content="text/plain; charset=utf-8"
$im =  imagecreatetruecolor ( 300, 200);
$black = imagecolorallocate ($im,  0, 0, 0);
$lightgray = imagecolorallocate ($im,  230, 230, 230);
$darkgreen = imagecolorallocate ($im,  80, 140, 80);
$white = imagecolorallocate ($im,  255, 255, 255);
 
imagefilledrectangle ($im,0,0,299,199 ,$lightgray);
imagerectangle ($im,0,0,299,199,$black);
imagefilledellipse ($im,150,100,210,110,$white);
imagefilledellipse ($im,150,100,200,100,$darkgreen);
header ("Content-type: image/png");
imagepng ($im);
?>

Figure 3.4. Verifying GD2 (checkgd2.php)

Verifying GD2 (checkgd2.php)

In the same way as before store this file on the server and point the browser to it. The result should be the same image as is shown in Figure 3.4

In order to use the library it is absolutely necessary that the above two scrips works as described. If this is not the case the php.ini file needs to be checked as described in the next section.

3.2.2. Enabling GD library in php.ini for PH5

If neither of the two example above worked and the GD section didn't exist in the output from phpinfo() the chances are that the GD library has not been enabled in the php.ini file.

The first problem to solve is therefore to locate the php.ini file in the installation. Depending on the type of server (and OS) this can be in different places. If the system is running on a Unix server the php.ini file is most likely stored in either /etc/php.ini , /etc/php/php.ini , /etc/php5/php.ini or /etc/php5/apache/php.ini

Tip

Check the output of phpinfo() to find out what php.ini file the installation is reading.

On a windows server there is no standard location since it completely depends on how the installation of the HTTP server and PHP was done. For example if the WAMP server was installed and put in the top directory c:\wamp\ the php.ini file is installed under c:\wamp\bin\apache\apache2.2.11\bin\php.ini

Open php.ini in a editor and locate the line

extension_dir = <some-path-here>

The directory path specified above is the directory where all PHP extension modules are stored. On a Unix system this is typically specified as /usr/lib/php5/extensions now examine that directory and check if an extension called "gd.so" (for Unix) or "gd.dll" (for Windows) exists (and is un-commented). If this extension cannot be found then this extension needs to be installed. For example, many Unix/Linux installation requires that the extra modules in PHP is manually enabled/installed through the appropriate Packet manager as the example below shows.

Example 3.3. Installing GD through RPM packet manager

$/> sudo zypper install php5-gd


3.2.3. Verifying TTF fonts

This section is only intended to verify if that support exists for TTF fonts. If this does not work or if it is already known that there are no support for TTF fonts then please go directly to Section 3.4

In order to check if basic TTF font support is available create the following script in the document root and name it checkttf.php

Then it is necessary to locate on the system exactly where the TTF fonts are stored and update the defines for the paths and/or the name of the TTF fonts that is know to exist.

Example 3.4. Verifying TTF with a known font (checkttf.php)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?php // content="text/plain; charset=utf-8"
// Change this defines to where Your fonts are stored
DEFINE("TTF_DIR","/usr/share/fonts/truetype/");
 
// Change this define to a font file that You know that You have
DEFINE("TTF_FONTFILE","arial.ttf");
 
// Text to display
DEFINE("TTF_TEXT","Hello World!");
 
$im = imagecreatetruecolor (400, 100);
$white = imagecolorallocate ($im, 255, 255, 255);
$black = imagecolorallocate ($im, 0, 0, 0);
$border_color = imagecolorallocate ($im, 50, 50, 50);
 
imagefilledrectangle($im,0,0,399,99,$white);
imagerectangle($im,0,0,399,99,$border_color);
imagettftext ($im, 30, 0, 90, 60, $black, TTF_DIR.TTF_FONTFILE,TTF_TEXT);
 
header ("Content-type: image/png");
imagepng ($im);
?>


Figure 3.5. Verifying TTF with a known font (checkttf.php)

Verifying TTF with a known font (checkttf.php)


As usual point the browser to this script and fetch the image. If thing works an image identical to what is shown in Figure 3.5 should be visible.

Name of TTF font files

The library has built in support for large number of TTF fonts, this includes both the standard MS WEB core fonts as well as Vera and DejaVu fonts. In addition a number of non-latin fonts are supported. This includes both Japanese, Chinese, Hebrew and Russian fonts. See Section 3.4.2 and Section 8.8 for more on how to use non-latin fonts and encodings.

In order for the fonts to be usable by the library the font files must have the following names (these are the standard names)

More information on how to use TTF fonts in scripts can be found in Chapter 8

Table 3.1. Latin TTF font file names

Font family nameSymbolic nameNormal, FS_NORMALBold, FS_BOLDItalic, FS_ITALICBold italic, FS_BOLDITALIC
CourierFF_COURIERcour.ttfcourbd.ttfcouri.ttfcourbi.ttf
GeorgiaFF_GEORGIAgeorgia.ttfgeorgiab.ttfgeorgiai.ttf 
TrebucheFF_TREBUCHEtrebuc.ttftrebucbd.ttftrebucit.ttftrebucbi.ttf
VerdanaFF_VERDANAverdana.ttfverdanab.ttfverdanai.ttf 
Times romanFF_TIMEStimes.ttftimesbd.ttftimesi.ttftimesbi.ttf
ComicFF_COMICcomic.ttfcomicbd.ttf  
ArialFF_ARIALarial.ttfarialbd.ttfariali.ttfarialbi.ttf
VeraFF_VERAVera.ttfVeraBd.ttfVeraIt.ttfVeraBI.ttf
Vera monoFF_VERAMONOVeraMono.ttfVeraMoBd.ttfVeraMoIt.ttfVeraMoBI.ttf
Vera serifFF_VERASERIFVeraSe.ttfVeraSeBd.ttf  
(Chinese) SimsunFF_SIMSUNsimsun.ttcsimhei.ttf  
ChineseFF_CHINESEbkai00mp.ttf   
(Japanese) MinchoFF_MINCHOipamp.ttf   
(Japanese) P MinchoFF_PMINCHOipamp.ttf   
(Japanese) GothicFF_GOTHICipag.ttf   
(Japanese) P GothicFF_PGOTHICipagp.ttf   
(Hebrew) DavidFF_DAVIDDAVIDNEW.TTF   
(Hebrew) MiriamFF_MIRIAMMRIAMY.TTF   
(Hebrew) AhronFF_AHRONahronbd.ttf   
DejaVu Sans SerifFF_DV_SANSSERIFDejaVuSans.ttfDejaVuSans-Bold.ttf, DejaVuSans-Oblique.ttfDejaVuSans-BoldOblique.ttf
DejaVu Sans Serif MonoFF_DV_SANSSERIFMONODejaVuSansMono.ttfDejaVuSansMono-Bold.ttfDejaVuSansMono-Oblique.ttfDejaVuSansMono-BoldOblique.ttf
DejaVu Sans Serif CondensedFF_DV_SANSSERIFCONDDejaVuSansCondensed.ttfDejaVuSansCondensed-Bold.ttfDejaVuSansCondensed-Oblique.ttfDejaVuSansCondensed-BoldOblique.ttf
DejaVu SerifFF_DV_SERIFDejaVuSerif.ttfDejaVuSerif-Bold.ttfDejaVuSerif-Italic.ttfDejaVuSerif-BoldItalic.ttf
DejaVu Serif CondensedFF_DV_SERIFCONDDejaVuSerifCondensed.ttfDejaVuSerifCondensed-Bold.ttfDejaVuSerifCondensed-Italic.ttfDejaVuSerifCondensed-BoldItalic.ttf


Note

For the DejaVu fonts there are actually two common sets of name in usage depending on how long it has been since the fonts where installed. The library knows of both sets of names and will try them in order selecting to use the first one available.

3.2.4. Support for different image formats

By default the standard GD image library supports the PNG graphic format.

Hence by default only PNG is supported. If JPEG support is needed this might require additional libraries that must be installed and enabled for usage by PHP/GD (in the php.ini file), again please see PHP documentation for specifics. For most practical purposes PNG is a better format since it normally achieves better compression then GIF (typically by a factor of 2 for the types of images generated by JpGraph).

In comparison with JPEG format PNG is also better for the type of images generated by this library.

So, the bottom line is that there should be very good reasons to choose any other image encoding formats than PNG. By default the image format is set to "auto". This means that JpGraph automatically chooses the best available image encoding format using the preferred order "PNG", "GIF" and "JPG".

No support for SVG

We have received may requests to add support for SVG image output. Unfortunately we have investigated this and concluded that it is (surprisingly!) not technically possible to do this. The main reason is that with the current standard there is no way to statically determine the bounding boxes for texts. This is further described in Appendix K