SVGGraph 3.0

Published

In my last news item I said I was going to work on version 3.0 of SVGGraph next, and that is what I have been doing. There is a lot more I want to do, but I could have spent months tinkering on the new version without ever being completely happy with it. So here it is.

The EmptyGraph

The example EmptyGraph above is something that I thought might be useful, and will become more useful when something else I have planned comes to fruition. At the moment it can be used to draw shapes and labels, plus it supports the graph title, border and background options. You can assign values, colours and links, but it doesn't do anything with them and you can get away with code as simple as this:

require 'SVGGraph/autoloader.php';

$graph = new Goat1000\SVGGraph\SVGGraph(600, 300);
$graph->render('EmptyGraph');

Without any settings this code will produce a SVG with a grey background and a single pixel black border - not particularly useful. This example does show some of the changes to the interface in version 3.0 though, which I will go through next.

1. Loading SVGGraph

The first change is that the script includes svggraph/autoloader.php instead of the main SVGGraph.php file.

// the SVGGraph 2.x way
require 'SVGGraph/SVGGraph.php';

// the SVGGraph 3.0 way
require 'SVGGraph/autoloader.php';

If you use Composer to load SVGGraph, then you don't need to worry about this because it is dealt with by SVGGraph's composer.json file. In previous versions of SVGGraph classes were loaded directly by the library, but version 3.0 has switched to using a PSR-4 autoloader.

If you want to configure your own autoloader, all the classes used by SVGGraph are in the Goat1000\SVGGraph namespace. Which brings me to the next change:

2. Creating an SVGGraph object

The minimum version of PHP supported by SVGGraph 3.0 is PHP 5.4. This means that it can now take advantage of namespace support instead of all the classes being named "SVGGraph<something>". To create an instance of the SVGGraph class, use the fully qualified namespace and class name:

// the SVGGraph 2.x way
$graph = new SVGGraph(400, 300, $settings);

// the SVGGraph 3.0 way
$graph = new Goat1000\SVGGraph\SVGGraph(400, 300, $settings);

// or create an alias
use Goat1000\SVGGraph\SVGGraph;

$graph = new SVGGraph(400, 300, $settings);

Using the alias might be easier if you have a lot of graph instances to update, it doesn't make any difference to how SVGGraph behaves.

3. Colours, Links, Values and function names

In previous versions of SVGGraph it was possible to assign values, colours and links by directly modifying the data members of the SVGGraph instance. This made validation really complicated, so it is not supported by SVGGraph 3.0 and will cause an error.

// the SVGGraph 2.x way
$graph->Values($values);
$graph->colours = array('red', 'green', 'blue');
$graph->links = array('http://www.goat1000.com/', '/this-link');

// the SVGGraph 3.0 way
$graph->values($values);
$graph->colours(['red', 'green', 'blue']);
$graph->links(['http://www.goat1000.com/', '/this-link']);

For SVGGraph 3.0, you must use the relevant function - any of the colour functions for setting graph colours, or the links function to set the links. The names of all functions in SVGGraph 3.0 have changed to camel case with a lowercase first letter. This doesn't really matter when using SVGGraph because function names are case-insensitive in PHP, but I will be updating the documentation to match.

In this latest example I used the short array syntax ([] instead of array()) to pass arrays into the functions - SVGGraph now uses this syntax internally because it makes code more compact and a bit easier to read.

Other changes

I have added a few new options, and removed an old one. The most interesting new option is line_breaks - this changes the behaviour of line graphs so that they leave a gap in the line when NULL values are encountered instead of bridging over the gap. This option is supported by all the line graphs except for the StackedLineGraph where it would make things very odd.

The other two new options are both for fine-tuning character conversion. The use_iconv and use_mbstring options can be set to false to prevent SVGGraph trying to use either of the extensions for conversions. The previous version of SVGGraph tested that the extensions were available for use, but it didn't know if the extensions were going to work or not. If you know that your version of iconv or mbstring doesn't work properly, these options allow you to turn them off.

The compat_events option has been removed. It enabled the use of old-style event handlers, which were only required for the old plugin-based SVG renderer. If you're stuck using a browser that only supports the old event handlers you have worse problems than missing tooltips.

On the other hand, missing tooltips are the first of the bugs fixed in this version. When using multiple graphs directly in the page at differing sizes the tooltips could disappear off the edge of the small graphs. The next bug fixed was the tail length of custom labels - setting it to "auto" wasn't working. The last bug was in the edge shading of 3D polar area graphs, which wasn't taking the radius of the slice into account when applying the gradient.

Version 3.0 of SVGGraph is available from the downloads page, or from GitHub / Packagist with Composer.

« Previous: SVGGraph 2.30 Next: SVGGraph 3.0.1 »