Many web sites need to create real-time or dynamic charts and graphs from live data sets. Many users have found PHP a great way for this dynamic creation of images using the GD library. The advantage of using the server to create an image (that is, using a server-side scripting language rather than a client-side language such as Java) is that one does not have to worry about browser compatibility or client operating system compatibility issues.

PHPlot is a specialized graphics library which provides a means for your PHP-enabled web server to create and manipulate graphs as objects and display the completed graph as an image. PHPlot uses the GD library to create elementary shapes such as lines, rectangles, and text, but hides the details of GD from the application programmer.

Data sets are passed to PHPlot using PHP arrays, in a convenient format for database-driven sites.

First, lets discuss how PHPlot works in general with some terminology. (More complete definitions can be found in Section 3.1, “Definitions”.) A PHPlot image can consist of several graphs (but usually has only one), each graph consisting of several elements (like lines, axes, and labels).

To use PHPlot, you create a PHP object from the PHPlot class, for example:

$plot = new PHPlot;

Then you set the properties of the object, by using a series of function calls (actually methods of the class). These define the characteristics of the image, the graph or graphs, and their elements. This includes setting the array containing the data to be plotted, defining titles if you want them, and many optional elements and style settings. You can think of this as "drawing" elements into the image, but in fact PHPlot just notes your intentions and doesn't do much until you are finished.

When you are done describing a graph, you instruct PHPlot to "draw" the graph into the image. When you are done with all graphs in an image, you need to instruct PHPlot to "print" (output) the image. Since most images contain only one graph, PHPlot simplifies this process by default. Unless instructed otherwise, PHPlot will "print" the image (output it to the browser) as soon as you tell it to "draw" (render) the first graph.

Usually, PHPlot will "print" the image directly to the user's browser. The result will be a complete HTTP response with headers, so your PHP script must not produce any other output (except for optional headers). The user will be see the image either as a result of accessing your script directly with a URL, like http://www.example.com/graphs/myplot.php, or you can embed the image in a web page using an image tag, like this:

<IMG SRC="http://www.example.com/graphs/myplot.php">

Instead of sending the image to the browser, your application can instead choose to write the PHPlot image to a file on the server. This could be useful if you want to implement server-side caching of image files. (PHPlot itself does not currently provide caching.)

Before continuing, we need to mention coordinates. PHPlot uses two coordinate spaces: one for the image, and one for the data you are plotting. World Coordinates are the X,Y coordinates of your data, relative to the axis origin, in the units of the data sets. Your data array uses world coordinates, as do tick mark labels on the X and Y axis. Device Coordinates measure pixels in the image according the the GD convention, with the origin in the upper left corner of the image. These are also called Pixel Coordinates. PHPlot tries to place elements on your graph appropriately, but if you need to override its choices you will use device coordinates to position the elements.

The rest of this chapter explains how to write a PHP script which creates a plot using PHPlot. Information on PHP can be found at www.php.net. Information about the GD library which PHP uses to create images can be found at libgd.org. More information about PHPlot can be found at phplot.sourceforge.net.