Less rigid API

Until this version, I was focusing on implementing strictly the Google Chart API. However, I eventually realize that the API is sometimes too rigid. For example, say you want to hide an axis. You have to specify “_” (underscore) as the 5th value (axis_or_tick) in the chxs parameter (values are separated by a coma). Looks easy right? Except it is NOT ok to omit the first 4th values. So you have to specify the label_color, font_size and alignment before, in order to be able to hide your axis.

In version 0.3, you had to do exactly that, by using setStyle and specifying the 4th parameter ($axis_or_tick). If you wonder why it’s not the 5th, it’s because the “axis index” value is calculated on runtime. Fortunatly, you could pass null as the value for the parameter, and the library will replace them by the default value. Example:

$axis = new GoogleChartAxis('x');
$axis->setStyle(null, null, null, '_');

In version 0.4, the setStyle method as been removed and splitted into multiple methods setLabelColor, setFontSize, setLabelAlignment, setDrawLine, setDrawTickMarks and setTickColor. Now you don’t need to worry about how many parameter you have to set, just call the method you want and the library will take care of setting the appropriate intermediate values. Example:

$axis = new GoogleChartAxis('x');
$axis->setDrawLine(false)->setDrawTickMarks(false);

More abstraction

This version also comes up with a set of features to simplify chart creation. For example, one of my favorite is setBorder method for Shape Markers (GoogleChartShapeMarker).

To create a border in a shape with Google Chart API, you need to create another similar marker below the first one (think z-order), with a different color and a slightly bigger size. Well, this can be done exactly this way in version 0.3. However, starting version 0.4, the setBorder method does the job for you. Just specify a color and the size of the border, and it will create the second marker automatically. Not only this is more convenient and easy to write, but this is also faster and uses less memory.

New features

This version adds support for Dynamic Icon. Because icons can be either “freestanding” (used as a chart) or used as marker, I had to refactor the base class. Now the base class is GoogleChartApi which holds the logic to query the API. GoogleChart and GoogleChartIcon extends this class, so you can use a GoogleChartIcon exactly the same way as a chart.

Example:

require '../lib/icons/GoogleChartIconNote.php';

$chart = new GoogleChartIconNote('Hello world');
$chart->setTitle('Example');
$chart->setTextColor('D01F3C');

header('Content-Type: image/png');
echo $chart;

To use a icon as a marker, use the new addDynamicMarker method. Example:

require '../lib/GoogleChart.php';
require '../lib/icons/GoogleChartIconNote.php';

$values = array();
for ($i = 0; $i <= 10; $i += 1) {
	$values[] = rand(20,80);
}

$chart = new GoogleChart('ls', 500, 200);
$data = new GoogleChartData($values);
$chart->addData($data);

$marker = new GoogleChartIconNote('Hello');
$marker->setData($data);
$chart->addDynamicMarker($marker);

header('Content-Type: image/png');
echo $chart;

For the moment, only “note” icon (aka Fun style notes with text and optional title) are supported, but I’m working on it.

Hey, the project has a new home!

Yes, the project is now hosted by Google Code. Because there is already a shitload of abandonned projects named using every possible combinations of “google” “chart” and “php”, I had to use the (rather long) name “googlechartphplib”. So new home is here:
http://code.google.com/p/googlechartphplib. You’ll find source code, issue tracker, documentation and the new SVN access there.

Quick introduction

The library’s goal is to provide an easy way to build requests to Google Chart API, and especially to ease the painfull strings concatenation with comas, pipes, colons, etc. If you’ve already tried Google Chart API, you know what I mean! :-) So I wrote a couple of class, that allows to quickly create a chart (GoogleChart), add data series (GoogleChartData), axes (GoogleChartAxis) and markers (GoogleChartMarker), and compute an URL (for GET requests) or an array of parameters (for POST requests). It can even fetch the image for you (via GET or POST) so that you can display it directly (or cache it, or do whatever you want with it).

I wanted to stick really closely to the actual Google Chart API. I hate having to fight with a library when I wanted to do some fancy stuffs with the API. So most of the time, the library will only provides an set of convenient setters stricly mapped on the API specification with almost no additional logic (there is also an universal setter if the setter you need is unimplemented yet. ;-) But YOU will have to check in the Google documentation for the list of supported parameters, or how to do some advanced stuff (compound charts, anyone?). If you give an unsupported parameter, you might get some unexepected results from Google Chart API. Only the cases that would makes the API send a error are checked.

In other words: this library is only an interface, the PHP logic is kept to the minimum. One exception here though: the library provide an autoscaling feature, because scaling manually your chart is a pain in the ass (this feature can be disabled if you want). Therefore if you’re not ready to read at least some of the Google Chart API documentation, this tool might not be for you.

A quick example

One quick example on how to create a line chart with 3 lines, 2 axis and some data markers.

require '../lib/GoogleChart.php';
require '../lib/markers/GoogleChartTextMarker.php';
require '../lib/markers/GoogleChartShapeMarker.php';

// create some random values
$values = array(
	array(),
	array(),
	array()
);
$n = 10;
for ($i = 0; $i <= $n; $i += 1) {
	$v = rand($i , $i*10);
	$values[0][] = $v;
	$values[1][] = $v - $i;
	$values[2][] = rand(100 - ($i+10),100 - 10*$i);
}

// create the chart and define some options
$chart = new GoogleChart('lc', 400, 200);
$chart->setGridLines(10,10);
$chart->setLegendPosition('r');
$chart->setFill('ffffcc');
$chart->setGradientFill(45, array('cccccc', 'ffffff', 'cccccc'), GoogleChart::CHART_AREA);
$chart->setTitle('Us versus the others.');
$chart->setTitleStyle('999999', 20);

// create the first line
$line = new GoogleChartData($values[0]);
$line->setLegend('Us');
$chart->addData($line);

// add markers to this line
$marker = new GoogleChartShapeMarker(GoogleChartShapeMarker::X);
$marker->setData($line);
$marker->setColor('6699cc');
$chart->addMarker($marker);

$marker = new GoogleChartTextMarker(GoogleChartTextMarker::VALUE);
$marker->setData($line);
$chart->addMarker($marker);

// define a dotted line (not displayed in the legend)
$line = new GoogleChartData($values[1]);
$line->setStyle(2,2,2);
$line->setColor('6699cc');
$chart->addData($line);

// define a red line
$line = new GoogleChartData($values[2]);
$line->setLegend('The others');
$line->setColor('ff0000');
$chart->addData($line);

// add markers
$marker = new GoogleChartShapeMarker(GoogleChartShapeMarker::CIRCLE);
$marker->setData($line);
$marker->setColor('ff0000');
$chart->addMarker($marker);

// add axis
$y_axis = new GoogleChartAxis('y');
$chart->addAxis($y_axis);

$x_axis = new GoogleChartAxis('x');
$chart->addAxis($x_axis);

// debug the chart
if ( isset($_GET['debug']) ) {
	var_dump($chart->getQuery());
	echo $chart->validate();
	echo $chart->toHtml();
}
// display the chart
else{
	header('Content-Type: image/png');
	echo $chart;
}

Generated chart (I copy/pasted the generated URL, this is not the actual PHP code):

Requirements and limitations

GoogleChart PHP library works with PHP 5.2 (maybe works with other version as well, I don’t know), and doesn’t require any additional library. It’s released under the MIT license. Current version is 0.3, meaning that a lot of features are unimplemented yet (but otherwise it works fine, believe me ;-). Current major limitations includes :

• Only support Basic Text Format and Text Format with Custom Scaling.
• Only tested with Line Charts, Map Charts and Bar Charts. It’s designed to handle any type though, so with a little bit of luck it might works for other charts as well.

And also, because it’s a side project I do during my spare time, I only implement the features that I need for my other projets, and only when I need them. So if have different needs and you’re willing to help, you’re welcome!

Download and install

GoogleChart PHP library is available for download here: http://redmine.kuerti.net/projects/googlechart/files http://code.google.com/p/googlechartphplib. The archive comes with plenty examples and Doxygen documentation. Just copy the content of the lib folder inside your project.

You can also checkout the latest SVN version here: http://svn.kuerti.net/googlechart/trunk http://googlechartphplib.googlecode.com/svn/trunk/.

Doxygen-generated documentation is available here. This documentation is not always up-to-date nor complete, but I’m working on it, I promise.

Send me feebacks, I love feedbacks

Feedbacks are more than welcome! Feel to send feature requests, bug reports and more here as a comment, or (better) on the project’s Redmine: http://redmine.kuerti.net/projects/googlechart the project homepage in Google Code: http://code.google.com/p/googlechartphplib/. And if you’re a developer and interested on improving it, feel free, it’s open source! Mails are also always welcome at remi at cloudconnected dot fr.