4.2 How to generate images with PHP

As a general rule each PHP script which generates an image must be specified in a separate file which is then called in an <IMG> tag reference. For example, the following HTML excerpt includes the image generated by the PHP script in "fig1.php".

 <img src="fig1.php" border=0
 align=center width=300 height=200>

The library will automatically generate the necessary headers to be sent back to the browser to correctly recognize the data stream as an image of either PNG/GIF/JPEG format. The browser can then correctly decode the image

Observere that you can't return anything else than an image from the image script. By definition each HTML page can only consist of one mime type which is determined by the sent headers.

A common mistake is to have a space in the beginning of the image script file which the HTTP server will send back to the browser. The browser now assumes that the data comming back from this script is normal ASCII. When then the image headers get send back to the browser to forwarn the browser of the forthcomming image the browser will not like that. It has already determined that the script should only send ASCII data back and will then give you a "Headers already sent error".

To include several images together with text on a page you need to have a parent page with several <IMG> which each refers to an image script.

To get access to the library you will need to include at least two files, the base library and one or more of the plot extensions. So for example if you want to do line plots the top of your PHP file must have the lines:

 php

include (
'jpgraph.php');

include ('jpgraph_line.php');

...

 // Code that uses the jpgraph
 library

...

Sidebar: You might also use the PHP directive requires(). The difference is subtle in that include will only include the code if the include statement is actually excuted. While require() will always be replaced by the file specified. See PHP documentation for further explanation. For most practical purposes they are identical.

4.3 The basic principle of JpGraph and the creation of images

You will see that the common pattern for creating graphs is to

Create a script that constructs the image, type, colors size and so on.
A wrapper script which contains one or more <IMG> tags to position the graphs on the proper HTML page.

Of course it is of perfectly possible to call the image script directly in the browser to just display the generated image in the browser.

You shopuld remember that it is also possible to pass arguments to the image script via the normal HTTP parameters, for example

 <img src="showgraph.php?a=1&b=2">

This could for example be used to control the apperance of the image or perhaps send data to the image which will be displayed. Note that this is probably not the best way to send large amount of data to plot. Instead the only practical way, for large data sizes, is to get all the data in the image script, perhaps from a DB.

Tips: Forcing the browser to update your image Some browser may not send back a request to the web browser unless the user presses "Refresh" (F5 - in most browsers). This can lead to problems that the user is seeing old data. A simple trick is to add a dummy time argument which is not used in the script. For example

 echo "<img
 src='myimagescript.php?dummy=".now()."'>"

When it comes to the structure of your imaging script they will generally have the structure

 // ... Include necessary headers

$graph = new Graph($width,$height, ...);

// ... code to construct the graph details

$graph->Stroke();

JpGraph is completely Object oriented so all calls will be action on specific instances of classes. One of the fundamental classes is the Graph() class which represents the entire graph.

After the creation of the Graph() object you add all your lines of code to construct the details of the graph.

As the final call you will send the generated image back to the browser with a call to the Stroke() method.

Note: This is not always true, but to keep things simple for the moment we assume this.

In addition to this standard usage pattern you can also send the graph directly to a file, get the GD image handler for the image and also make use of the builtin cache system. The cache system, which lessens the burden of the PHP server, works by avoiding o run all the code that follows the initial Graph() call by checking if the image has already been created and in that case directly send back the previously created (and filed) image to the browser. When using the cache system you must specify a filename which is used to store the image in the cache system and possibly also a timeout value to indicate how long the image in the cache directory should be valid. For this reason you might in the following examples, for example, see the code

 $graph = new Graph(300,200,"auto");

in the start of all the examples. The two first parameters specify the width and height of the graph and the third parameter the name of the image file in the cache directory. The special name 'auto' indicates that the image file will begiven the same name as the image script but with the extension changed to indicate the graphic format used, i.e '.jpg', '.png' and so on.

4.4 Chosing the image format for JpGraph

By default JpGraph automatically chooses the image format to use in the order PNG, JPEG and GIF. The exact format depends on what is available on your system. There are two ways you can influence the way the graphic format is choosen.

Change the default graphic format by changing the DEFINE

DEFINE("DEFAULT_GFORMAT","auto");
Set the graphic format in your script by calling the method SetImgFormat() For example, to force your script to use JPEG in one specific image use

$graph->img->SetImgFormat("jpeg")

4.5 Alternatives to streaming back the image

If you like to save the image directly to a file instead of streaming it back to the browser then you just have to specify an absolute filename in the final call to Graph::Stroke(), i.e.

 $graph->Stroke("/usr/home/peter/images/result2002.png");

Please note that the user running as Apache/PHP must have write access to the specified directory.

There are also two predefined filenames which have special meaning.

"auto", This will create a file in the same directory as the script with the same name as the script but with the correct image extension.
_IMG_HANDLER, (This is defined in jpgraph.php). Specifying this filename will not create a an image to file or stram it back to the browser. Instead it will instruct the Stroke() method to just return the handle for the GD image. This is usefull if you later want to manipulate the image in ways that are not yet supported by Jpgraph. For example include the image in generated PDF files.
Example:

$handle = $graph->Stroke(_IMG_HANDLER);

Contents Previous Next