I’ve been playing around a lot with Google Chart API lately, mainly for fun to draw some charts based on my Last.fm profile (Last.fm provides a very nice API). Google Chart API is very powerful, but quite harsh to work with, and unfortunately I didn’t find any good and easy-to-use PHP library for it. There are some but most of them are either not maintened or not fully working. So I ended up writting my own library. A few weeks ago, I used it for a project at work, improved it a bit and it worked like a charm. Eventually I decided to release it open-source (MIT license). It’s provided “as is”, without warranty of any kind. I just hope that it might be useful to somebody else as well, who knows?
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/trunkhttp://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.