Charting with PHP

Brent Knigge

brenlei.com

The appetizer

Let's wet your appetite with the wow factor

• Sample Charts

Here's a chart from some actual contract work I've done which will now form the basis of the charting discussion tonight.

Downloading the Pear Packages

The charts were developed using a couple of the pear graphic packages, and these are listed below in the order that they need to be installed. These packages also require the gd2 PECL extension to be loaded with PHP.

• Numbers_Words
• Numbers_Roman
• Image_Color
• Image_Canvas
• Image_Graph

Installing Pear Packages 1

Installing a pear package can be a little daunting at first (especially if it doesn't work) so I'll highlight a couple of steps to help you on the way.

Installing a pear package can be done in two ways with the pear installer

• A) connected to the internet via the package channel
• B) offline with the downloaded zip file

I've only ever used option B simply because I'm not actually connected to the internet at home

Installing Pear Packages 2

pear should be installed by default with PHP version 5, so you should be able to type pear at the command prompt and be displayed with the help menu

A small portion of the help file

We are primarily interested in info, list and install commands with pear

Installing Pear Packages 3

Once we have downloaded the necessary zip files, we can install them

pear install filename

Installing the barcode package

You will find it helpful to navigate to the directory where the zip file is located, and begin the install from there.

Installing Pear Packages 4

pear list lists the packages that we have installed. If you look closely you might see a couple of topics that might make for an interesting presentation. The recently installed barcode package, and the Archive_TAR package.

pear packages installed on my PC

Documentation

Like most pear packages, the documentation for the charting package is embedded within the actual PHP script itself. I've used the phpDocumentor GUI to parse the PHP files and generate standalone documentation for the package.

If done correctly, you'll end up with very gucci documentation

Generating the Documentation

These packages look like fun. Infact I dare say some will become integral to your business. But you quickly run out of fun if you have no workable documentation for the package you want to use.

Unfortunately phpDocumentator is a topic unto itself, so I wont have time to explore this package except to tease you with another screen shot

Generating the Documentation 2

Using phpDocumentor is quite intuitive. Commenting your code so that phpDocumentor can parse it is a different story - one that will be shared at another time

Chart Code 1

Here is some code to start us off. You will notice some oddities, and that is because the library is written in PHP4

require_once 'Image/Graph.php';

//$Graph =& Image_Graph::factory('graph', array(800, 800));
$Graph =& Image_Graph::factory('graph', array(array('width' => 500,
                                                    'height' => 300,
                                                    'canvas' => 'png')));

//use a different font and size from the default.
$Font =& $Graph->addNew('font', 'Verdana');
$Font->setSize(9);

$Graph->setFont($Font);

Chart Code 1a

Once I've set up my graph, I can start looking at adding some data. Notice that I have 2 datasets, and this correlates to the 2 different coloured bars in the chart.

$Dataset =& Image_Graph::factory('dataset');
$Dataset->addPoint('1.01-1.50', 0);
$Dataset->addPoint('1.51-2.00', 0);
...
$Dataset2 =& Image_Graph::factory('dataset');
...
$Dataset2->addPoint('4.01-4.50', 10);
$Dataset2->addPoint('4.51-5.00', 5);

Chart Code 1b

How about adding a name to each of the datasets. While we are at it, we also need to create a plotarea, and add it to the graph. (Oh yeah, you can have more than one plot area)!!

//this is how to name each dataset.
$Dataset->setName('2006');
$Dataset2->setName('2007');
//-----

//This is how to create a plotarea and add it to the graph.
$Plotarea = &Image_Graph::factory('plotarea', array('Image_Graph_Axis_Category',
                                                    'Image_Graph_Axis',
                                                    'vertical'));
$Plotarea =& $Graph->add($Plotarea);
//-----

Chart Code 1c

Now that we have a plotarea, and a name for our datasets, lets add a legend and do some funky stuff with it.

//this is how to add a legend
$Legend =& $Plotarea->addNew('legend');
$Legend->setFillColor('white@0.7');
$Legend->setFontSize(8);
$Legend->showShadow();
//-----

Incase that's not enough, we can always check out the help file and find some more methods to play around with.

Chart Code 1d

The chart will normally scale the y-axis to the height of the tallest data point. I needed to force it to 100. Notice the label interval, tick options and the title that is displayed vertically.

//this is how to modify the axis.
$axisY =& $Plotarea->getAxis('y');
$axisY->forceMaximum(100);

$axisY->setLabelInterval(5, 2);
$axisY->setTickOptions(-1, 1, 2);
$axisY->setTitle('Percentage', 'vertical');
//-----

Chart Code 1e

Normally the x-axis will display the label for the data point. $Dataset2->addPoint('4.01-4.50', 10); but the label in the data point will be too wide. Let's use our own label and force it onto 2 lines.

//this is how to change/format the labels on the x-axis.
$AxisX = $Plotarea->getAxis(IMAGE_GRAPH_AXIS_X);
$AxisX->setTitle('Summation of Mean Ratings');

$Array = array('1.01-1.50' => "  1.01-\n1.50",
               '1.51-2.00' => "  1.51-\n2.00",
               ...
$AxisX->setDataPreprocessor(Image_Graph::factory('Image_Graph_DataPreprocessor_Array',                                                    array($Array)));
//-----

Chart Code 1f

Notice how the chart had the text 'Strongly Agree' and 'Strongly Disagree' at the either end of the range. The chart library doesn't have a specific function for that, but you can use the write function to write anywhere on the chart (I think).

$AxisX->write(50, 268, "Strongly\nDisagree");
$AxisX->write(440, 268, "Strongly\nAgree");

Chart Code 1g

Those cool line markers going across at 25, 50 and 75 provide a nice visual cue to the viewer of how far above or below key values are. You'll notice with the function calls that we can infact have line markers on either the y or x axis

//this is how to add a line marker..
$MarkerY1 =& $Plotarea->addNew('Image_Graph_Axis_Marker_Line', null, IMAGE_GRAPH_AXIS_Y);
$MarkerY1->setLineColor('red');
$MarkerY1->setValue(25);

This section of code is repeated for each line marker (i.e. for 50 and 75).

Chart Code 1h

Remember those datasets we created. Well they need to be added to the plotarea. I add 2 datasets to the plotarea, but I've also shown how to add just one dataset.

$Plot =& $Plotarea->addNew('Image_Graph_Plot_Bar', array(array(&$Dataset, &$Dataset2)));

//$Plot =& $Plotarea->addNew('Image_Graph_Plot_Bar', array($Dataset));

Chart Code 1i

Now those cool bars didn't come coloured by themselves. This section shows how to colour the bars, and the setSpacing gives us a little spacing between the sets. The @0.5 et el sets the opacity.

$Fill =& Image_Graph::factory('Image_Graph_Fill_Array');
$Fill->addColor('red@0.5');
$Fill->addColor('blue@0.2');
$Plot->setFillStyle($Fill);
$Plot->setSpacing(10);

Chart Code 1j

Don't forget to add a bit of padding to the axis, and also a title. Notice how the title has been added. A quick glance at the documentation reveals 29 properties that can be used with the addNew function. We've used 5 so far.

$Plotarea->setAxisPadding(2, 'left');
$Plotarea->addNew('title', array('Charting with PHP', array('size' => 13)));
$Plotarea->setAxisPadding(10, 'top');

//output the chart to file
$Graph->done(array('filename' => 'output.png'));

//output the chart to the browser
//$Graph->done();

Chart Code 2a

Lets have a look at a slightly different chart.

$Plotarea = &Image_Graph::factory('plotarea', array('Image_Graph_Axis_category',
                                                    'Image_Graph_Axis',
                                                    'horizontal'));

$Plot =& $Plotarea->addNew('Image_Graph_Plot_Bar', array(array(&$Dataset, &$Dataset2)));

$Plot2 =& $Plotarea->addNew('Image_Graph_Plot_Line', array(&$Dataset3));

Chart Code 3a

That line chart overlay looked pretty crappy. What I think we needed was a marker.

$Plot2 =& $Plotarea->addNew('Image_Graph_Plot_Dot', array(&$Dataset3));

$Marker1 =& Image_Graph::factory('Image_Graph_Marker_Cross');
$Marker1->setFillColor('blue');
$Marker1->setLineColor('black');

$Plot2->setMarker($Marker1);