3.7. Troubleshooting the installation

Unfortunately there are many parameters in a server installation that may affect the execution of PHP so the steps below can only give some indications of how to further investigate some potential problems.

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. So before starting trouble shooting the scripts please make sure that you have an up to date PHP installation with the bundled version of the GD library (as describe in the previous sections) and a working FreeType library installed.

  1. No image is displayed.

    The first thing you should do is to isolate the problem by calling your graph script directly in the browser. There are then two variants of this problem.

    1. No data is sent back from the server.

      You can verify this by calling your graph script directly in the browser and then check the source (click "view source" menu item in the browser). If this is a truly blank image then no data was sent back from the browser.

      This means that the PHP process has been terminated prematurely before it could send any data back. This could be caused by either the PHP process crashing (due to a bug in either PHP or your HTTP server) or the HTTP server crashed. This is often due to a broken PHP installation and more than often a problem with the True Type libraries.

      It could also be caused by the PHP script running longer than the maximum allowed execution time (as specified in php.ini). The first thing you should do is to increase the maximum allowed execution time. If this does not solve the problem you should look in the log files for both your HTTP server and PHP to try to find clues to if the PHP process really crashed. Another possibility is that the PHP process uses more than the maximum allowed memory (as set in php.ini) and then it is terminated. So a good first step is to put some really high values for memory and time just to take away these parameters.

    2. The data sent back is corrupt.

      Depending on your browser this can show up differently but a common symptom is a "red X" in the browser. In order to debug this you should make sure that you have followed the steps in Section 3.3.1 to make sure you have output buffering disabled and have maximum error checking enabled in PHP. The most common cases for this type of problem is having enabled output buffering and some minor errors in the script which causes PHP to emit warnings which gets included in the image data.

      A very common mistake is to have some white spaces in the script before the opening "<?php". This white space will be added to the output buffer and then get mixed up with the image data causing the image data to be corrupt. A similar problem can occur if multiple newlines are added after the final "?>"

  2. An error message saying "Fonts are not available or not readable"

    When an image contains TTF fonts you might get an error message saying that the fonts are not available or not readable. If this is the case it is first necessary to check that the font files really exist in the directory that is specified in jpg-config.inc.php and that they are also readable by the HTTP/PHP process. If this is the case then it is necessary to check that the names of the font files are the one that JpGraph assumes, see the section called “Name of TTF font files”. Another problem can be if the PHP installation is running in "safe mode" (See PHP Manual: Security and safe mode) and has enabled strict directory policy via an "open_basedir" restriction. This will prevent the PHP process from reading any files outside the specified base directory. If this is enabled there is no way around for PHP to read any files outside this restriction and any TTF files necessary must be moved so that they can be accessed within the realms of the specified basedirectory.

    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 the 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 are running on Unix server please keep in mind that file names are case sensitive.

  3. An error message saying "Headers have already been sent"

    A common mistake is to have a space in the beginning of the image script which the HTTP server will send back to the browser. The browser now assumes that the data coming back from this script is text since it hasn't received an explicit header. When then the image headers get sent back to the browser to forewarn the browser of the forthcoming image data the browser will not like that as it has already assumed the data stream was a text stream. The browser will then give the infamous "Headers already sent error".

    Make sure that your script has no white space before the opening "<?php" statement or a number of blank lines after the concluding "?>"

  4. Issues specific to Windows and IIS

    Some windows installations seems to have a problem with a PHP script ending in more than one newline (This newline seems to be sent to the browser and will cause a Header already sent error). To correct this problem check all your scripts for more than one empty newline after the ending "?>" statement. All files provided with the library end in exactly one final newline and should not be a problem.

  5. TTF fonts are not displayed correctly

    If the TTF fonts only shows up as yellow then the installation is used a buggy (too old) installation of the FreeType font library and the only thing to do is to re-install and setup PHP+GD again with a newer version of the FreeType library. Another symptom of a an (old) buggy FreeType library is that the fonts are not correctly rotated (the text string is rotated but not the individual characters).

As a final advise you should read the FAQ (available in this manual see Appendix C) or on the JpGraph website at http://www.aditus.nu/jpgraph/jpgraphfaq.php

Depending on your sever it might also help to recompile PHP yourself instead of the version included with the system. You can find typical configuration scripts to compile PHP4 and PHP5 in the appendices, see Appendix I