You might not have known this, but PHP comes with one very useful and unique feature: the ability to dynamically create images at run-time. This feature opens the door to all manner of nifty things, including, for example, the ability to display graphs of your Web site traffic in real time, or visually view the movement of your stock portfolio.
That's where this tutorial comes in. I'm going to show you how to use PHP's built-in image generation capabilities with the very cool BarGraph class to create graphs and bar charts on the fly. So keep reading—this is going to be fun.
The BarGraph class is an open source class developed and maintained by Diogo Resende. It is designed specifically to ease the task of dynamically generating bar graphs in PHP, by allowing you to specify X- and Y-axis values in an array and then using that data to create the graph for you.
The BarGraph class also allows you to control all aspects of the graph, including axis scales, colors, borders, and titles.
To get started, download the class and extract it to a directory under your Web server root. Note that in order to successfully use the BarGraph class, you need PHP 4.3.2 or better, with support for the GD extension.
Once you're all set up, type the script shown in Listing A to see how the class works:
When you run the script in Listing A, you should see a graph similar to Figure A.
After initializing an object of the BarGraph() class, a PHP associative array is created. This array contains the raw data that will be used to generate the graph. In this array, every key represents an item on the X-axis, and the corresponding value represents the quantity of that item on the Y-axis. You can use alphabetic or numeric key names, but the values for each must be numeric.
Once this raw array has been set up, the next step is to pass it to SetBarData() method as an argument. This method takes care of parsing the data values, and performing the necessary calculations to generate the graph. The actual generation of the chart is done by the DrawGraph() function, which internally uses PHP's image generation API to create the axes, the axis points, and the bars themselves.
Now that we've covered the basics, your next question is sure to be, how do I customize it to my specific requirements of color and size? First, if you look closely at the graph generated by the previous listing, you'll see that the Y-axis isn't very neat. This is primarily because I didn't specify a step value for the Y-axis scale, and so BarGraph() attempts to put a very detailed numerical scale on that axis, resulting in an unreadable mess.
Take a look at Listing B and its output shown in Figure B, which corrects this error.
By setting a step value for the Y-axis, the axis becomes less cluttered with numbers, and this in turn makes it easier to visually approximate the value of each item. Notice also my use of the SetGraphTitle() method to set a title for the graph.
Adjusting padding, margins, and colors
How about adjusting the space around the graph, or the dimensions of the bars? Sure, you can do that, as you can see in Listing C.
The code in Listing C will produce Figure C.
As you can see, this is quite different from the previous images—and not just because I've used different values. There are a number of new methods in this script, related to both the graph and the bars within it. The SetGraphAreaHeight() method sets the height of the graph, the SetGraphPadding() method controls the space between the graph and the image borders, and the SetGraphBorderWidth() method sets the thickness of the image border.
In the context of the bars themselves, the SetBarPadding() method controls the space around the bars, while the SetBarDimensions() method controls the height and width of the bars. This last method is particularly important if you'd like to give your chart that cool 3D effect you see in Figure C.
And finally, we come to those all-important colors. Consider the script in Listing D, which demonstrates the methods available to alter the graph's color scheme.
Figure D shows what it looks like.
Yup, it almost made me blind too!
The BarGraph class allows you to adjust two attributes of each element: the border color and the background color. The elements that can be controlled in this manner are the graph itself, the axes and the bars. Listing D illustrates the methods for each, with colors specified in RGB format.
Applying a style sheet
If you have a lot of charts to be generated, and you'd like to apply a uniform style to all, you can avoid the numerous method calls above and simply place your settings in a separate graph definition file. This file can then be read by the BarGraph() class, and its contents used to control the final output.
To see how this works, create a text file containing the script shown in Listing E.
Save this file as style.txt. Next, create a PHP script (Listing F) that imports this external stylesheet into the BarGraph() object, and uses it to generate a chart. In this script, a new LoadGraph() method has been introduced. This method reads a definition file like the one above, and uses the settings inside it to customize the bar chart. This is a simple way of applying a uniform style to your charts, and also reduces the total number of lines of code in your script.
Figure E shows you what it all looks like.
And that's about it for this tutorial. You now know enough to go out there and begin creating stunning bar charts of your own. So what are you waiting for?