At some point, most developers have a need to create graphs. I've known some to get frustrated and end up exporting the data to a spreadsheet, rather than relying upon the graphing capabilities of Open Office or Excel. That can be the way to go in certain cases, but not because there's no alternative. PHP has some great graphing libraries; JpGraph is probably the most well-known, but it can require a commercial licence. This article looks at PEAR's Image_Graph package, which is released under the Lesser GPL. It's a package that has very little documentation, but which deserves more recognition. It's helpful to have used PEAR before, but if this is the first PEAR package you'll use, you'll probably cope just fine.
Formerly a SourceForge package known as GraPHPite, it merged with and took the name of an older PEAR Image_Graph package. The graphs, charts and plots produced by Image_Graph are highly customizable, and can be any of area, band, bar, box and whisker, candlestick, impulse, map, line, pie, radar, scatter, smoothed line and step.
Requirements
To install Image_Graph, you need:
- PHP 4.3.0 or later (it works with PHP 5)
- GD (GD 2 is recommended)
- PEAR support
- The Image_Canvas package
- The Image_Color package
Installing
Installing packages on PEAR is easy using the pear command. You can see what PEAR packages are already on your system by running pear list. A default installation may look like this:
$ pear list Installed packages: =================== Package Version State Archive_Tar 1.1 stable Console_Getopt 1.2 stable DB 1.6.2 stable HTTP 1.2.2 stable Mail 1.1.3 stable Net_SMTP 1.2.6 stable Net_Socket 1.0.1 stable PEAR 1.3.2 stable XML_Parser 1.0.1 stable XML_RPC 1.1.0 stable
There are two main ways to install a PEAR package. You can install directly from the PEAR server, or you can download and install from your local machine. The mechanism is effectively the same. Some packages are still in alpha, including Image_Graph, so it won't appear on the main list of stable packages that are available (which you can view by running pear remote-list.
In this article we'll install by downloading. Assuming you have a default install, you'll need to download the following three packages: Image_Color, Image_Canvas and Image_Graph. Note that there may be newer versions out by the time you do this. It's unlikely, but you should also check to see if there're any new dependencies (they'll be listed on the download page). To install them, simply run the pear install command. Make sure you get the order right to avoid any dependency failures.
$ pear install Image_Color-1.0.2.tgz install ok: Image_Color 1.0.2 $ pear install Image_Canvas-0.3.0.tgz install ok: Image_Canvas 0.3.0 $ pear install Image_Graph-0.7.2.tgz Optional dependencies: package `Numbers_Roman' is recommended to utilize some features. package `Numbers_Words' is recommended to utilize some features. install ok: Image_Graph 0.7.2
The Numbers_Roman and Numbers_Words packages are optional extras, but we're not going to use them for our purposes here.
A Simple Bar Chart Example
Creating a bar chart is probably easiest of all. Let's start with some sample code to do just that. The examples are going to hardcode the data, but I'm sure you're more than capable of reading the data from a database or some other source, and that'll just complicate the graphing examples.
image_graph.php
<?php
include 'Image/Graph.php';
$Graph =& Image_Graph::factory('graph', array(600, 300));
$Plotarea =& $Graph->addNew('plotarea');
$Dataset =& Image_Graph::factory('dataset');
$Dataset->addPoint('Jan', 5);
$Dataset->addPoint('Feb', 13);
$Dataset->addPoint('March', 10);
$Plot =& $Plotarea->addNew('bar', &$Dataset);
$Plot->setLineColor('green');
$Plot->setFillColor('cadetblue');
$Plot->setBackgroundColor('green@0.1');
$Graph->done();
?>
The first line:
include 'Image/Graph.php';
is all that's required to use the Image_Graph package. Include it first in any code that will need graphing. The next line,
$Graph =& Image_Graph::factory('graph', array(600, 300));
instantiates the graph object, and creates a canvas 600 pixels wide by 300 pixels high. It makes use of the Factory design pattern. You don't have to use this pattern, but it makes your life a bit easier. A discussion of the factory design pattern is beyond the scope of this article, but all it really means for our purposes is that you usually only need to have the one include statement (above). The next line:
$Dataset =& Image_Graph::factory('dataset');
creates a dataset, which will contain the data to use in creating the graph. There are two main types of datasets: the ordinary one, used here, which is basically an array of data points, and a more complex function-based one, which we'll look at later. Next, the data points are added:
$Dataset->addPoint('Jan', 5);
$Dataset->addPoint('Feb', 13);
$Dataset->addPoint('March', 10);
Having defined the plotarea, as well as the data points, all that's needed is to define the plot that will appear on the plotarea.
$Plot =& $Plotarea->addNew('bar', &$Dataset);
There can be multiple plots, but in this case there's just one. There are also multiple plot types (as mentioned earlier), but we're just adding a simple bar graph for now. Finally, the done method renders the graph:
$Graph->done();
Try experimenting with different values, and different numbers of values. You'll notice that the largest value always fills up 100% of the space, and the others fill an area in proportion to this. If 10 is your highest value, a point with a value of 5 fills up 50%, while if 20 is your highest value, the 5 fills up 25%. All this should be expected with bar graphs.
Some Color
With the default settings, your graph is hardly going to win any awards. Let's make it a little more readable with some colors.
image_graph2.php
<?php
include 'Image/Graph.php';
$Graph =& Image_Graph::factory('graph', array(600, 300));
$Plotarea =& $Graph->addNew('plotarea');
$Dataset =& Image_Graph::factory('dataset');
$Dataset->addPoint('Jan', 5);
$Dataset->addPoint('Feb', 13);
$Dataset->addPoint('March', 10);
$Plot =& $Plotarea->addNew('bar', &$Dataset);
$Plot->setLineColor('green');
$Plot->setFillColor('cadetblue');
$Plot->setBackgroundColor('green@0.1');<php
include 'Image/Graph.php';
$Graph =& Image_Graph::factory('graph', array(600, 300));
$Plotarea =& $Graph->addNew('plotarea');
$Dataset =& Image_Graph::factory('dataset');
$Dataset->addPoint('Jan', 5, 'J');
$Dataset->addPoint('Feb', 13, 'F');
$Dataset->addPoint('March', 10, 'M');
$Plot =& $Plotarea->addNew('bar', &$Dataset);
$Plot->setLineColor('green');
$Plot->setBackgroundColor('green@0.1');
$fill =& Image_Graph::factory('Image_Graph_Fill_Array');
$fill->addColor('red', 'J');
$fill->addColor('blue', 'F');
$fill->addColor('yellow', 'M');
$Plot->setFillStyle($fill);
$Graph->done();
?>
$Graph->done();
?>
You can use any of the 147 SVG color names, as well as hex values to define your colours if you wish. The methods are clearly named, so what they do should be fairly self-explanatory.
Fill Arrays
You're also likely to want to use different colours for different bars. To do this, we need to give each dataset a unique identifier, as well as use a fill array to match the colours with the element. Here's an example:
image_graph3.php
<?php
include 'Image/Graph.php';
$Graph =& Image_Graph::factory('graph', array(600, 300));
$Plotarea =& $Graph->addNew('plotarea');
$Dataset =& Image_Graph::factory('dataset');
$Dataset->addPoint('Jan', 5, 'J');
$Dataset->addPoint('Feb', 13, 'F');
$Dataset->addPoint('March', 10, 'M');
$Plot =& $Plotarea->addNew('bar', &$Dataset);
$Plot->setLineColor('green');
$Plot->setBackgroundColor('green@0.1');
$fill =& Image_Graph::factory('Image_Graph_Fill_Array');
$fill->addColor('red', 'J');
$fill->addColor('blue', 'F');
$fill->addColor('yellow', 'M');
$Plot->setFillStyle($fill);
$Graph->done();
?>
What's new here is that we're using the Image_Graph_Fill_Array class. Then a color is assigned to each element, based on the name it was given when it was defined. It's also possible to leave out the name, in which case it will be assigned from first to last element, but it's a much better practice to specifically assign these rather than rely on the order they were added.
Fonts and Titles
image_graph4.php
<?php
include 'Image/Graph.php';
$Graph =& Image_Graph::factory('graph', array(600, 300));
$Plotarea =& $Graph->addNew('plotarea');
$Dataset =& Image_Graph::factory('dataset');
$Dataset->addPoint('Jan', 5, 'J');
$Dataset->addPoint('Feb', 13, 'F');
$Dataset->addPoint('March', 10, 'M');
$Plot =& $Plotarea->addNew('bar', &$Dataset);
$Plot->setLineColor('green');
$Plot->setBackgroundColor('green@0.1');
$fill =& Image_Graph::factory('Image_Graph_Fill_Array');
$fill->addColor('red', 'J');
$fill->addColor('blue', 'F');
$fill->addColor('yellow', 'M');
$Plot->setFillStyle($fill);
$Font =& $Graph->addNew('ttf_font', 'Bitstream-Vera-Sans-Mono');
$Font->setSize(12);
$Graph->setFont($Font);
$YAxis =& $Plotarea->getAxis(IMAGE_GRAPH_AXIS_Y);
$YAxis->setTitle('Rainy Days', 'vertical');
$XAxis =& $Plotarea->getAxis(IMAGE_GRAPH_AXIS_X);
$XAxis->setTitle('Month');
$Graph->done();
?>
First, the font used for the text elements is set to the ttf font Bitstream-Vera-Sans-Mono, size 12. A common error at this point would be something like:
Warning: imagettfbbox(): Could not find/open font in /usr/share/php/Image/Canvas/GD.php on line 1245
This occurs if you don't have the correct (or any) fonts in your Fonts directory, found at php/Image/Canvas/Fonts/. Make sure that you have the corresponding .ttf file located in your Fonts directory. For the above example we require Bitstream-Vera-Sans-Mono.ttf. Next, the x and y axes are given titles. Note that the y-axis title runs vertically.
Multiple Plotareas
As mentioned earlier, a single graph can have multiple plotareas. In this next example, there are three plotareas on the graph:
image_graph5.php
<?php
include 'Image/Graph.php';
$Graph =& Image_Graph::factory('graph', array(600, 300));
$Graph->add(
Image_Graph::horizontal(
Image_Graph::vertical(
$PlotareaTopLeft = Image_Graph::factory('plotarea'),
$PlotareaBottomLeft = Image_Graph::factory('plotarea'),
60
),
$PlotareaRight = Image_Graph::factory('plotarea'),
30
)
);
$Dataset =& Image_Graph::factory('dataset');
$Dataset->addPoint('Jan', 5, 'J');
$Dataset->addPoint('Feb', 13, 'F');
$Dataset->addPoint('March', 10, 'M');
$Plot =& $PlotareaRight->addNew('bar', &$Dataset);
$Plot->setLineColor('green');
$Plot->setBackgroundColor('green@0.1');
$fill =& Image_Graph::factory('Image_Graph_Fill_Array');
$fill->addColor('red', 'J');
$fill->addColor('blue', 'F');
$fill->addColor('yellow', 'M');
$Plot->setFillStyle($fill);
$Font =& $Graph->addNew('ttf_font', 'Bitstream-Vera-Sans-Mono');
$Font->setSize(12);
$Graph->setFont($Font);
$YAxis =& $PlotareaRight->getAxis(IMAGE_GRAPH_AXIS_Y);
$YAxis->setTitle('Rainy Days', 'vertical');
$XAxis =& $PlotareaRight->getAxis(IMAGE_GRAPH_AXIS_X);
$XAxis->setTitle('Month');
//2nd Plotarea
$Plot2 =& $PlotareaTopLeft->addNew('pie', &$Dataset);
$Plot2->setLineColor('green');
$Plot2->setBackgroundColor('green@0.2');
$fill =& Image_Graph::factory('Image_Graph_Fill_Array');
$fill->addColor('red', 'J');
$fill->addColor('blue', 'F');
$fill->addColor('yellow', 'M');
$Plot2->setFillStyle($fill);
//3rd Plotarea
$Plot3 =& $PlotareaBottomLeft->addNew('line', &$Dataset);
$Plot3->setLineColor('green');
$Plot3->setBackgroundColor('green@0.3');
$Graph->done();
?>
First, the graph is divided horizontally into two areas: the leftmost plotarea which is taking up 30% of the space, and the right one which is taking up the remainder. The left area is then further broken into two plotareas, the top one taking up 60% of the space. Using the same dataset, we create two new types: a pie graph and a line graph. There are a number of possible types. We'll look at them in more detail in a future article, but the list consists of:
- line (Image_Graph_Plot_Line)
- area (Image_Graph_Plot_Area)
- bar (Image_Graph_Plot_Bar)
- smooth_line (Image_Graph_Plot_Smoothed_Line)
- smooth_area (Image_Graph_Plot_Smoothed_Area)
- pie (Image_Graph_Plot_Pie)
- step (Image_Graph_Plot_Step)
- impulse (Image_Graph_Plot_Impulse)
- dot (Image_Graph_Plot_Dot)
- scatter, a synonym for dot
- radar (Image_Graph_Plot_Radar)
- Image_Graph_Plot_CandleStick
- Image_Graph_Plot_Band
A Heading
Finally, we'll add a title to the graph. A title is placed in an area that's assigned in the same way as the earlier three plotareas. We'll add another vertical division at the top, 5% high, for our heading.
<?php
include 'Image/Graph.php';
$Graph =& Image_Graph::factory('graph', array(600, 300));
$Graph->add(
Image_Graph::vertical(
Image_Graph::factory('title',array('3 graph rainy day',12)),
Image_Graph::horizontal(
Image_Graph::vertical(
$PlotareaTopLeft = Image_Graph::factory('plotarea'),
$PlotareaBottomLeft = Image_Graph::factory('plotarea'),
60
),
$PlotareaRight = Image_Graph::factory('plotarea'),
30
),
5
)
);
$Dataset =& Image_Graph::factory('dataset');
$Dataset->addPoint('Jan', 5, 'J');
$Dataset->addPoint('Feb', 13, 'F');
$Dataset->addPoint('March', 10, 'M');
$Plot =& $PlotareaRight->addNew('bar', &$Dataset);
$Plot->setLineColor('green');
$Plot->setBackgroundColor('green@0.1');
$fill =& Image_Graph::factory('Image_Graph_Fill_Array');
$fill->addColor('red', 'J');
$fill->addColor('blue', 'F');
$fill->addColor('yellow', 'M');
$Plot->setFillStyle($fill);
$Font =& $Graph->addNew('ttf_font', 'Bitstream-Vera-Sans-Mono');
$Font->setSize(12);
$Graph->setFont($Font);
$YAxis =& $PlotareaRight->getAxis(IMAGE_GRAPH_AXIS_Y);
$YAxis->setTitle('Rainy Days', 'vertical');
$XAxis =& $PlotareaRight->getAxis(IMAGE_GRAPH_AXIS_X);
$XAxis->setTitle('Month');
//2nd Plotarea
$Plot2 =& $PlotareaTopLeft->addNew('pie', &$Dataset);
$Plot2->setLineColor('green');
$Plot2->setBackgroundColor('green@0.2');
$fill =& Image_Graph::factory('Image_Graph_Fill_Array');
$fill->addColor('red', 'J');
$fill->addColor('blue', 'F');
$fill->addColor('yellow', 'M');
$Plot2->setFillStyle($fill);
//3rd Plotarea
$Plot3 =& $PlotareaBottomLeft->addNew('line', &$Dataset);
$Plot3->setLineColor('green');
$Plot3->setBackgroundColor('green@0.3');
$Graph->done();
?>
Conclusion
There's a lot more to Image_Graph than we've managed to cover here. We'll take a further look in a future article, but hopefully this will give you a taste for further exploration of this powerful package on your own. Good luck!
Other Links