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.

Basic usage

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.

Figure A

Initial graph

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.

Figure B

Adjusted axis

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.

Figure C

Adjusting features

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.

Figure D

Bright Color

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.

Figure E

Stylesheet information

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?