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 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.