Contents Previous Next

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 verion 4.02 or above of PHP since JpGraph will not work with versions prior to PHP 4.02 that. Ideally you should use at least PHP 4.1.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.
 

header ("Content-type: image/png" );
$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 );
ImagePng ($im);

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

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 jpgraph.php

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 genereate 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

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 dependiong on what kind of graph you need to create.

3.4 Graphic libraries requirements for PHP 4.02 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".

Note: The reason that my site (www.aditus.nu) only displays GIF images is that my Web hotell doesn't support a newer version of GD which allows PNG format. One of lifes small pains. This is the reason that I in most places just displays the PNG images directly in the img tag on my site without going through Jpgraph since the GIF format gives much bigger files and would make my site slower.


Sidenote 2: To get background images working with GD 2.0.1 you MUST enable Truecolor images by setting the constant USE_TRUECOLOR to true. If you don't do this the background images will just be a black rectangle. The bad thing with this is that the antialias for Truetypes is broken using truecolor images in GD 2.0.1. This means you can't have background and TTF fonts in the same image.

You can find a bug fix for GD 2.01 and the TTF problem together with Truecolor images at

http://www.coupin.net/gd-freetype/

NOTE: This bug fix has _nothing_ to do with JpGraph and I can't guarantee anything nor answer any questions regarding this specific fix.


3.5 Detailed steps to install JpGraph

  1. Make sure your PHP is AT LEAST 4.04 (preferrable 4.1.1) and that you have compiled support for GD library. You must make aboslutely sure that you have GD working. Please run phpinfo() to check if GD library is supported in your installation. Please not that JpGraph only fully supports GD 1.x. There are known issues with GD 2.0.1 , see the notes section below.
  2. Unzip and copy the files to a directory of your choice.
  3. Set up the directory paths in jpgraph.php where the cache directory should be and where your TTF directory is. Note that Apache/PHP must have write permission in your cache directory.
  4. 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).
  5. Make sure PHP have write privileges to your cache directory if you plan on using the cache feature.
  6. 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
  7. It has been reported that PHP 4.06 under IIS has problem correctly interpreting file paths. This can be solved by hardcoding the CACHE_DIRECTORY and FONT_DIRECTORY constants directly in the code instead of using the defined constants.
  8. Read (really!) the JpGraph FAQ.

3.6 Troubleshooting your installation

  1. Any PHP errors about function "imagecreate" does not exist indicates that your PHP installation does not include the GD library. This must be present.
  2. Any error about "parent::" undefined means that you are not using PHP 4.02 or above. You _NEED_ PHP 4.02 or higher. This problem has also been reported to sometimes occur under Windows. This problem has also been reported by people running Zend-cache and is a bug in Zend. A workaround is to move all files into one single file.
  3. 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 truecolor support. Correct this by enabling the USE_TRUECOLOR define.
  4. 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!
  5. If you are running PHP 4.06 and get an error saying "GD was not built with truetype support" you should know that this is a known problem with GD+PHP 4.06. There are some workarounds (search the net!) but it is really recommended that you instead upgrade to at least PHP 4.1.1 and configure PHP with --with-gd-native-ttf (Please also note that the built in TTF uses point size for fonts whereas Truetype 2 uses pixels.) Please DON't ask me how to resolve the GD Font problem. All mail regarding this will go straight to /dev/null. Upgrade to 4.1.1!
  6. 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.
  7. 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.
  8. If you have problem building GD 2.0.1 for PHP you might want to try the following tip from Rasmus L.
  9.   ----<QUOTE >----
    
       Build GD 2.0.1 with these two lines in your GD2 Makefile
    
       CFLAGS=-g -DHAVE_LIBPNG -DHAVE_LIBJPEG -DHAVE_LIBFREETYPE
       LIBS=libgd.a -lpng -lz -ljpeg -freetype -lm
    
       Don't install the lib anywhere, just leave it in the GD-2.1.1
       directory.
    
       Then build PHP using a minimum of:
    
       --with-gd=/home/
    
    /gd-2.0.1
       --with-freetype-dir=/use
       --enable-gd-native-ttf
       --enable-gd-imgstrttf
       --with-jpeg-dir=/usr
       --with-png-dir=/usr
       --with-xpm-dir=/usr/X11R6
    
       The above assumes you have freetype2 installed along with the
       libjpeg and libpng libs under /usr
    
       ---- <END QUOTE >----
    

Contents Previous Next