3.2. Programming Overview

3.2. Programming Overview
Prev	Chapter 3. PHPlot Concepts	Next

This section contains an overview of how to use PHPlot.

3.2.1. How It Works

To create a plot with PHPlot, your PHP script will generally do the following:

Include the phplot.php source using require_once.
Create an object which is an instance of the PHPlot class.
Use PHPlot functions (methods of the class object) to select the plot type, present the data array, and optionally change settings which control the appearance of the plot.
Output the plot, typically to the user's browser but possibly to a file instead.

The order of operations you use between creating a PHPlot object and output of the plot does not matter. The PHPlot class sets internal class variables as you configure the plot, but doesn't do anything with the values until you are ready. For example, setting a font for the plot title, then setting the title text, is the same as setting the title text first, then the font. In both cases, the title will be drawn using the font you selected.

Note

It is important to remember that if you are writing a PHP script that uses PHPlot to create an image for a web page, that PHP script must output only the image data. If you want your plot image to appear on a web page with text and other images, you need at least two scripts. Your main script returns an HTML page which includes an IMG (Image) tag for the plot. The IMG tag has a SRC attribute which references the second script, and it is this second script which creates the PHPlot image. An example of this can be found in Section 5.23, “Example - Complete Web Form with Plot”. You will most likely need a way to communicate parameters from your main script to your image script. Two good ways to do this are using URL parameters, and with PHP session variables.

An alternative to using two scripts - one generating HTML, and one using PHPlot to create the plot image - is available starting with PHPlot-5.5.0. You can write a single script which generates HTML and also embeds the PHPlot-generated plot image. See Section 5.39, “Example - Embedding Image with EncodeImage”.

3.2.2. Annotated Example

Here is a simple, annotated example of a script which produces an image. More examples can be found in Chapter 5, PHPlot Examples.

require_once 'phplot.php';

This brings in the PHPlot source into your script. For this to work, PHP needs to be able to find the PHPlot source file. A good way to arrange this is to install PHPlot into a directory outside your web server's document root and on the PHP Include Path. Other ways are to include a full path to phplot.php when including it, or to copy phplot.php into the same directory as your script.

$plot = new PHPlot();

Here we create a new PHPlot object and call it plot. Everything else we do with the plot will be through the $plot object.

$plot->SetPlotType('lines');
$plot->SetDataType('text-data');

Here we select the plot type 'lines', for a line plot (see Section 3.4, “PHPlot Plot Types”), and indicate our data will be represented in the 'text-data' format (see Section 3.3, “PHPlot Data Types”).

$plot->SetDataValues($data);

The data array $data is where we store the values to be plotted. We haven't shown where the data came from, but in a typical application it might be from a database query. How the data array is constructed is described in Section 3.3, “PHPlot Data Types”.

$plot->SetXDataLabelPos('none');
$plot->SetLineWidths(3);
$plot->SetDrawXGrid(True);

These three functions illustrate how to change the appearance of the plot.

$plot->DrawGraph();

This final function call outputs the plot. More accurately, this function creates the plot using all the data and settings which were established by previous functions, and then outputs the plot. This is a crucial point when using PHPlot: Until you call DrawGraph, PHPlot is simply recording all the settings resulting from the functions you call, and saving a copy of your data array. Nothing really happens until you complete the plot with DrawGraph.