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.
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.
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,
Store this basic program as
phpinfo.php in the document
root. Then point the browser to
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
There are three important points to notice here.
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.
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.
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
Example 3.1. Verifying the GD installations (
1 2 3 4 5 6 7 8 9 10 11
// 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
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 (
1 2 3 4 5 6 7 8 9 10 11 12 13 14
// 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
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.
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
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
Check the output of
phpinfo() to find out what
php.ini file the installation is
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
php.ini file is
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
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
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 (
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
// 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
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.
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 name||Symbolic name||Normal, ||Bold, ||Italic, ||Bold italic, |
|(Japanese) P Mincho||FF_PMINCHO|
|(Japanese) P Gothic||FF_PGOTHIC|
|DejaVu Sans Serif||FF_DV_SANSSERIF|
|DejaVu Sans Serif Mono||FF_DV_SANSSERIFMONO|
|DejaVu Sans Serif Condensed||FF_DV_SANSSERIFCOND|
|DejaVu Serif Condensed||FF_DV_SERIFCOND|
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.
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".
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