Necessary system requirements for the library
| Chapter 3. The Long Version: Installing the Library |

## 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.

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

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. Verifying the GD installations (`checkgd.php`) 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`)`

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. Verifying the GD installations `(`checkgd.php`)`

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`)`

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. Verifying GD2 `(`checkgd2.php`)`

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.

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

### 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 Installing and configuring Font support

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`)`

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. Verifying TTF with a known font `(`checkttf.php`)` 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 Using non-latin based fonts with JpGraph and Character encoding 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. Text and font handling

Table 3.1. Latin TTF font file names

Font family name | Symbolic name | Normal, `FS_NORMAL` | Bold, `FS_BOLD` | Italic, `FS_ITALIC` | Bold italic, `FS_BOLDITALIC`
--- | --- | --- | --- | --- | ---
Courier | FF_COURIER | `cour.ttf` | `courbd.ttf` | `couri.ttf` | `courbi.ttf`
Georgia | FF_GEORGIA | `georgia.ttf` | `georgiab.ttf` | `georgiai.ttf` |
Trebuche | FF_TREBUCHE | `trebuc.ttf` | `trebucbd.ttf` | `trebucit.ttf` | `trebucbi.ttf`
Verdana | FF_VERDANA | `verdana.ttf` | `verdanab.ttf` | `verdanai.ttf` |
Times roman | FF_TIMES | `times.ttf` | `timesbd.ttf` | `timesi.ttf` | `timesbi.ttf`
Comic | FF_COMIC | `comic.ttf` | `comicbd.ttf` |  |
Arial | FF_ARIAL | `arial.ttf` | `arialbd.ttf` | `ariali.ttf` | `arialbi.ttf`
Vera | FF_VERA | `Vera.ttf` | `VeraBd.ttf` | `VeraIt.ttf` | `VeraBI.ttf`
Vera mono | FF_VERAMONO | `VeraMono.ttf` | `VeraMoBd.ttf` | `VeraMoIt.ttf` | `VeraMoBI.ttf`
Vera serif | FF_VERASERIF | `VeraSe.ttf` | `VeraSeBd.ttf` |  |
(Chinese) Simsun | FF_SIMSUN | `simsun.ttc` | `simhei.ttf` |  |
Chinese | FF_CHINESE | `bkai00mp.ttf` |  |  |
(Japanese) Mincho | FF_MINCHO | `ipamp.ttf` |  |  |
(Japanese) P Mincho | FF_PMINCHO | `ipamp.ttf` |  |  |
(Japanese) Gothic | FF_GOTHIC | `ipag.ttf` |  |  |
(Japanese) P Gothic | FF_PGOTHIC | `ipagp.ttf` |  |  |
(Hebrew) David | FF_DAVID | `DAVIDNEW.TTF` |  |  |
(Hebrew) Miriam | FF_MIRIAM | `MRIAMY.TTF` |  |  |
(Hebrew) Ahron | FF_AHRON | `ahronbd.ttf` |  |  |
DejaVu Sans Serif | FF_DV_SANSSERIF | `DejaVuSans.ttf` | `DejaVuSans-Bold.ttf`, | `DejaVuSans-Oblique.ttf` | `DejaVuSans-BoldOblique.ttf`
DejaVu Sans Serif Mono | FF_DV_SANSSERIFMONO | `DejaVuSansMono.ttf` | `DejaVuSansMono-Bold.ttf` | `DejaVuSansMono-Oblique.ttf` | `DejaVuSansMono-BoldOblique.ttf`
DejaVu Sans Serif Condensed | FF_DV_SANSSERIFCOND | `DejaVuSansCondensed.ttf` | `DejaVuSansCondensed-Bold.ttf` | `DejaVuSansCondensed-Oblique.ttf` | `DejaVuSansCondensed-BoldOblique.ttf`
DejaVu Serif | FF_DV_SERIF | `DejaVuSerif.ttf` | `DejaVuSerif-Bold.ttf` | `DejaVuSerif-Italic.ttf` | `DejaVuSerif-BoldItalic.ttf`
DejaVu Serif Condensed | FF_DV_SERIFCOND | `DejaVuSerifCondensed.ttf` | `DejaVuSerifCondensed-Bold.ttf` | `DejaVuSerifCondensed-Italic.ttf` | `DejaVuSerifCondensed-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.

### 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. Why it is not possible to add a SVG backend to JpGraph

| Up |
| Home |