3 Installation

3.1 Preparation

In general the only thing you need to do is to make sure your PHP files can include the required library files (as described below) and that your PHP installation supports at least one graphic format, i.e. it supports the "image" extension to PHP.

You can easily verify this by making sure that your installation of PHP supports some of the 'imagecreate()' functions.

This means that you must have a working GD-library together with PHP before even thinking of running JpGraph. Please make sure you have version 4.1 or above of PHP since JpGraph is not tested with versions prior to PHP 4.1. Ideally you should use at least PHP 4.3.x

If you want to use TTF fonts you must also make sure that your PHP installation supports TTF fonts (either through FreeType 1 or FreeType 2 libraries). In additions to this you need at least a couple of TTF fonts. In preparation of using TTF fonts with JpGraph you must specify, in jpgraph.php , where those font files can be found.

JpGraph uses a naming convention for the TTF font files in order to be able to find the correct font files. You should therefore use the font files that can be downloaded together with JpGraph.

In order to make sure that you have GD installed you could try by running the following example which creates a very simple image using just pure GD calls and outputs an image in PNG format.

 $im = @ImageCreate (50, 100)

    or die ("Cannot create a new GD image.");

$background_color = ImageColorAllocate ($im, 255, 255, 255);

$text_color = ImageColorAllocate ($im, 233, 14, 91);

ImageString ($im, 1, 5, 5,  "A Simple Text String", $text_color);

header ("Content-type: image/png");

ImagePng ($im);

The above script must work before you will have any chance of getting JpGraph working.

3.1.1 Verifying that you have GD2 installed

To access the more advanced features of JpGraph you need GD 2.x library. This will allow you to use features as alphablending and trucolor images. To make sure that you have GD 2.x the following script must be working.

 $im = imagecreatetruecolor (300, 200);

 $black = imagecolorallocate ($im, 0, 0, 0);

 $white = imagecolorallocate ($im, 255, 255, 255);

 imagefilledrectangle($im,0,0,399,99,$white);

 imagerectangle($im,20,20,250,190,$black);

 header ("Content-type: image/png");

 imagepng ($im);

After running this script you should now see a black rectangle in your browser.

3.1.2 Using non-latin based fonts with JpGraph

In addition to European font it is also possible to use non-latin based fonts such as Cyrillic, Japanese and Chinese.

In all cases you must have a suitable TTF font that supports the non-latin based language you want to use.

For Cyrillic support you need to set the define LANGUAGE_CYRILLIC in jpgraph.php to true. You can then use a suitable Cyrillic font as replacement for the ordinary fonts.

For Chinese JpGraph supports both BIG5 and gb2312 encoding. For BIG5 encoding your PHP installation must have support for the "iconv()" function. Furthermore you need to set the define CHINESE_TTF_FONT to the name of the Chinese BIG5 font you want to use. By default this is set to "bkai00mp.ttf". To use the Chinese BIG5 font for your texts you need to specify the font family as FF_CHINESE.

If you instead want to use the simsun.ttc of simhei.ttf fonts which use the gb2312 encoding you only need to install those fonts in the normal TTF font directory and then specify the font family as FF_SIMSUN (the simhei.ttf is used when you specify the fonts style as FS_BOLD.

3.2 Customizing the installation

In order for JpGraph to work you must adjust the cache and TTF directory to suit your installation. By default the TTF directory is "/usr/local/fonts/ttf/" and for the cache "/tmp/jpgraph_cache/". These are defined as PHP defines at the top of jpg-config.inc

Please make sure that PHP has write permissions to the cache directory if you plan to use the cache feature. If not you will get a "Can't write file xxx.yyy" error when you try to generate a graph. You can read more about how to use the cache in the chapter Making sense of caching system in JpGraph

3.3 Required files

This is the base library files, which you must have

Jpgraph.php, base library, always needed

3.3.1 Plot extension modules

To add plots to the graph you will need one or more of the following files plot extension files depending on what kind of graph you need to create.

jpgraph_log.php, Plot extension to support logarithmic X and Y scales
jpgraph_line.php, Plot extension. Needed to draw various line plots
jpgraph_bar.php, Plot extension. Needed to draw various bar plots
jpgraph_error.php, Plot extension. Needed to draw various error plots
jpgraph_scatter.php, Plot extension. Needed to draw scatter and impuls plots.
jpgraph_spider.php, Plot extension. Needed to draw spider plots.
jpgraph_pie.php, Plot extension. Needed to draw Pie plots
jpgraph_pie3d.php, Plot extension. Needed to draw 3D Pie plots
jpgraph_gantt.php, Plot extension. Needed to create gantt plots
jpgraph_radar.php, Plot extension. Needed for radar plots
jpgraph_polar.php, Plot extenion. Needed for Polar plots
jpgraph_gantt.php, Plot extension. Needed for Gantt charts
jpgraph_regstat.php, Statistic extension. Needed to plot spline curves
jpgraph_stock.php, Plot extension. Needed to plot stock charts
jpgraph_gradient.php, Internal module. Contains all color gradient
jpgraph_gb2312.php, Handling of gb2312 font encoding (used for some chinese fonts)
jpgraph_plotmark.inc, Handling of plotmarks in line and scatter plot.
jpgraph_iconplot.php, Handling icons (small images) that can be added to the plots
jpgraph_plotband.php, Handling of plotbands added to the graphs
jpgraph_flags.php, Handling of country flags used as plot marks or as backgrounds.
imgdata_*.inc, Encoded images for plotmarks
flags*.dat, Image data for flags. Pre-compiled data for country flags.
jpgraph_canvas.php, Plot extension to make it possible to draw arbitrary graphic on a canvas.
jpgraph_canvtools.php, Add on to the canvas graph to provide an easier way to draw arbitrary shapes.

In the pro-version the following files are also available

jpgraph_windrose.php, Windrose plot extension
jpgraph_odo.php, Odometer plot extension
jpgraph_barcode.php, Linear barcode extension
jpgraph_pdf417.php, PDF417 2D Barcode extension

3.4 Graphic libraries requirements for PHP 4.1 and above

Per default the standard GD image library supports PNG graphic formats. You will need to have that installed together with your PHP module for this library to work at all. Please refer to PHP documentation on specifics. Note that the newer versions of GD does not support the GIF format due to copyright problems. Hence by default only PNG is supported.

If you want JPEG support you will also need an additional library for PHP, 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, you should have a very good reason to choose any other format then PNG.

By default the image format is set to "auto". This means that JpGraph automatically chooses the best available graphic using the preferred order "PNG", "GIF", "JPG".

3.5 Detailed steps to install JpGraph

Make sure your PHP is AT LEAST 4.2 (preferable 4.3.1 >= 1) and that you have compiled support for GD library. You must make absolutely sure that you have GD working. Please see the earlier sections on how to make sure. JpGraph supports both GD 1.x and GD 2.x However it is strongly recommended to use GD 2.x since that will improve performance and support true color images as well as alphablending.
Unzip and copy the files to a directory of your choice.
Set up the directory paths in jpg-config.inc where the cache directory should be and where your TTF directory is. Note that Apache/PHP must have write permission in your cache directory.
Check that all rest of the DEFINE in the top of JpGraph.php is setup to your preference. The default should be fine for most users. (See also Note 5. below) Specifically check that the settings of USE_GD2_LIBRARY reflects your installation, (should be true if you have GD2 installed, false otherwise).
Make sure PHP have write privileges to your cache directory if you plan on using the cache feature.
Some windows installations seems to have a problem with a PHP script ending in a newline (This newline seems to be sent to the browser and will cause a Header already sent error). If you have this problem try remove all trailing newlines in the jpgraph* files
Read (really!) the JpGraph FAQ.

3.6 Troubleshooting your installation

For 99% of the users this library will work directly with a recent installation of PHP without any problem. However if you are experiencing problem this can Unfortunately be tricky to hunt down due to the complex nature of the full PHP setup.

Experience shows that most of the trouble are caused by either an old buggy version of the free-type TTF library or using an old antiquated version of the GD library. In order to narrow it down you could try the following steps.

If you don't get any background images (but rather a solid black box) you are using GD 2.x but have forgotten to enable true color support. Correct this by enabling the USE_TRUECOLOR define.
If background images does not work make sure the settings of USE_GD2_LIBRARY corresponds to your installation, i.e. If you don't have GD2 then this define must be false!
If you are running IIS and Win2k and get the error "Can't find font" when trying to use TTF fonts then try to change you paths to UNIX style, i.e. "/usr/local/fonts/ttf/". Remember that the path is absolute and not relative to the htdocs catalogue.
If you don't get any image back at all then there is a big chance that your Apache module has crashed. This is often due to a broken PHP installation and more than often problem with the True Type libraries. Please look in your Apache error log or system log to try to trace any crashes.
The other reasons is that in some rare cases the auto detection of the GD library could get it wrong. If you in fact only have GD1 when the library mistakenly thinks you have GD2 this could in rare cases cause PHP to crash. Please try re-run the example by setting the DEFINE USE_GD2_LIBRARY to "false".
If you are using the cache please make sure that you have set the permissions correctly for the cache directory so that Apache/PHP can write to that directory.
If your TTF fonts only shows up as yellow then you have a buggy installation of the freetype font library and the only thing to do is to re-install PHP with a new version of the freetype library.

Contents Previous Next