SVGGraph 2.5 - a PHP SVG graph library
SVGGraph is an object-oriented PHP library for creating simple PHP graphs, released as open source under the LGPL v3 license. Here are some examples of different types of graph supported by SVGGraph.
Download a copy of the library here: SVGGraph2.5.zip [65k] or SVGGraph2.5.tar.bz2 [39k].
If you are still using PHP4, then you should use version 1.2.1 of SVGGraph: SVGGraph.zip [35k] or SVGGraph.tar.bz2 [25k]. Please read the included README.txt file for the correct instructions for the earlier version.
This library provides PHP classes and functions for easily creating SVG graphs from data. As of version 2.0, SVGGraph works with PHP 5 only, PHP 4 support has been dropped.
Here is a basic example:
$graph = new SVGGraph(640, 480); $graph->colours = array('red','green','blue'); $graph->Values(100, 200, 150); $graph->Links('/Tom/', '/Dick/', '/Harry/'); $graph->Render('BarGraph');
This will create a SVG file containing a 640x480 bar graph with three hyperlinked bars.
Graph types
At the moment these types of graph are supported by SVGGraph:
Bar graphs
| Class name | Description |
|---|---|
| BarGraph | Vertical bars, optionally hyperlinked. |
| Bar3DGraph | A 3D-looking version of the BarGraph type. |
| StackedBarGraph | Vertical bars, with multiple datasets stacked. |
| GroupedBarGraph | Vertical bars, with multiple datasets grouped side-by-side. |
For more details and examples, see the bar graph page.
Horizontal bar graphs
| Class name | Description |
|---|---|
| HorizontalBarGraph | Horizontal bars, optionally hyperlinked. |
| HorizontalStackedBarGraph | Horizontal bars, with multiple datasets in-line. |
| HorizontalGroupedBarGraph | Horizontal bars, with multiple datasets grouped vertically. |
For more details and examples, see the horizontal bar graph page.
Line and scatter graphs
| Class name | Description |
|---|---|
| LineGraph | A line joining the data points, with optionally hyperlinked markers at the data points. |
| MultiLineGraph | Multiple lines joining the data points in each data set, with optionally hyperlinked markers at the data points. |
| ScatterGraph | Markers drawn at arbitrary horizontal and vertical points. |
| MultiScatterGraph | Markers from multiple data sets drawn at arbitrary horizontal and vertical points. |
For more details and examples, see the line graph page.
Pie graphs
| Class name | Description |
|---|---|
| PieGraph | A pie chart, with optionally hyperlinked slices and option to fade labels in/out when the pointer enters/leaves a slice. |
| Pie3DGraph | A 3D-looking version of the PieGraph type. |
For more details and examples, see the pie graph page.
Using SVGGraph
The library consists of several class files which must be present. To use SVGGraph, include or require the main SVGGraph.php class file in your PHP code. The other classes should be in the same directory as the main file to be loaded automatically.
Embedding SVG in a page
There are several ways to insert SVG graphics into a page. FireFox, Safari, Chrome, Opera all support SVG, though Internet Explorer versions up to 8 currently require the use of a plugin (such as the one supplied by Adobe).
For options 1-3, I'll assume you have a PHP script called "graph.php" which contains the code to generate the SVG.
Option 1: the embed tag:
<embed src="graph.php" type="image/svg+xml" width="600" height="400" pluginspage="http://www.adobe.com/svg/viewer/install/" />
This method works in all browsers, though the embed tag is not part of the HTML standard.
Option 2: the iframe tag
<iframe src="graph.php" type="image/svg+xml" width="600" height="400"></iframe>
This method also works in all browsers, and the iframe tag is standard.
Option 3: the object tag
<object data="graph.php" width="600" height="100" type="image/svg+xml" />
The object tag is standard, but this doesn't work in IE.
Option 4: using the svg namespace within an xhtml document
This option is more complicated, as it requires changing the doctype and content type of the page being served. The SVG is generated as part of the same page.
<?php header('content-type: application/xhtml+xml; charset=UTF-8'); // $graph = new SVGGraph(...); // $graph setup here! ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:svg="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en"> <head> <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" /> <title>SVGGraph example</title> </head> <body> <h1>Example of SVG in XHTML</h1> <div> <?php echo $graph->Fetch('BarGraph', false); ?> </div> </body> </html>
This method allows you more control over how you use the SVG, though again it doesn't work in IE.
The SVGGraph class constructor
The SVGGraph class constructor takes three arguments, the width and height of the SVG image in pixels and an optional array of settings to be passed to the rendering class.
Note that the width and height you specify here should
be the same as or smaller than the size you use for the embed,
iframe or object element, otherwise you will end
up with scroll bars.
$graph = new SVGGraph($width, $height, $settings);
For more information on what goes in the $settings array,
see the settings section below.
Assigning data values
For simple graphs you may set the data to use by passing it into the Values
function:
$graph->Values(1, 2, 3);
For more control over the data, and to assign labels, pass the values in as an array:
$data = array('first' => 1, 'second' => 2, 'third' => 3); $graph->Values($data);
For graphs that support multiple data sets, pass in an array of value arrays:
$data = array( array('first' => 1, 'second' => 2, 'third' => 3), array('first' => 3, 'second' => 5, 'third' => 2, 'fourth' => 4), array('first' => 2, 'second' => 3, 'third' => 1, 'fifth' => 5), ); $graph->Values($data);
In this example, the second and third value arrays have extra values with keys 'fourth' and 'fifth'. The graph will be drawn with both of those values assumed to be 0 for the value arrays where they are not specified.
Graphs that do not support multiple datasets will use the first value array and ignore any others that are present.
For scatter graphs, the marker positions are given by the array keys and values:
$data = array(5 => 20, 6 => 30, 10 => 90, 20 => 50); $graph->Values($data);
From version 2.4, scatter graphs support passing in pairs of x,y coordinates
when the scatter_2d option is set, to allow several markers to
appear at the same x-coordinate:
$data = array( array(5,20), array(6,30), array(5,90), array(10,50) ); $graph->Values($data);
Adding hyperlinks
The graph bars and markers may be assigned hyperlinks - each value that requires
a link should have a URL assigned to it using the Links function:
$graph->Links('/page1.html', NULL, '/page3.html');
The NULL is used here to specify that the second bar will not be linked to
anywhere.
As with the Values function, the list of links may be passed in as an array:
$links = array('/page1.html', NULL, '/page3.html');
Using an associative array means that NULL values may be skipped.
$links = array('first' => '/page1.html', 'third' => '/page3.html'); $graphs->Links($links);
Rendering the graph
To generate and display the graph, call the Render function passing in the
type of graph to be rendered:
$graph->Render('BarGraph');
This will send the correct content type header to the browser and output the SVG graph.
The Render function takes two optional parameters in addition to the graph
type:
$graph->Render($type, $header, $content_type);
Passing in FALSE for $header will prevent output of the XML declaration and
doctype. Passing in FALSE for $content_type will prevent the image/svg+xml
content type being set in the response header.
To generate the graph without outputting it to the browser you may use the
Fetch function instead:
$output = $graph->Fetch('BarGraph');
This function also takes an optional $header parameter:
$output = $graph->Fetch($type, $header);
Passing in FALSE as $header will prevent the returned output from containing
the XML declaration and doctype. The Fetch function never outputs the content
type to the response header.
Colours
The colours used may be overridden from the default random set by setting the
graph's colours array.
$graph->colours = array('red', 'green', '#00ffff', 'rgb(100,200,100)', array('red','green'));
You may use any of the standard named colours, or hex notation, or RGB notation. The final entry in the example array is an array of two colours, which specifies a vertical gradient, the first colour (red) at the top and the second (green) at the bottom.
From version 2.1, more colours may be used in gradients, and a final 'h' or 'v' in the array will specify whether the gradient should be vertical (the default) or horizontal.
Gradients are supported by the bar graphs and for the filled area under line graphs. Where gradients are not supported, the first colour in the array will be used instead.
Examples:array('red','white','red','h'); // a horizontal gradient, red at both sides and white in the centre array('red','white','blue'); // a vertical gradient, red at the top, white in the centre, blue at the bottom array('red','orange','yellow','green','blue','indigo','violet','h'); // a horizontal rainbow gradient
How the colours are used depends on the type of graph being rendered.
For the bar and pie graphs, each bar or pie slice is assigned the next colour in
turn from the list of colours, repeating the sequence when the list is exhausted.
For the line graphs, the colours are used to fill the area under the line (if the
fill_under option is enabled).
Settings
Many of the ways that things are displayed may be changed by passing in an array of settings to the SVGGraph constructor:
$settings = array('back_colour' => 'white'); $graph = new Graph($width, $height, $settings);
The list of options that are valid for all types of graph and their default values are shown below. Sizes are always in pixels. Because the settings are stored in a standard PHP array, numbers and boolean values should be represented without quotes, and all other values should be quoted with either single or double quotes.
| Option | Default | Description |
|---|---|---|
| title | NULL | Contents of title tag, or NULL for none |
| description | NULL | Contents of desc tag, or NULL for none |
| stroke_colour | rgb(0,0,0) | Colour of graph lines |
| stroke_width | 1 | Thickness of graph lines, 0 disables line drawing |
| back_colour | rgb(240,240,240) | Background colour of graph |
| back_round | 0 | Radius of rounded background edge |
| back_stroke_width | 1 | Thickness of background edge |
| back_stroke_colour | rgb(0,0,0) | Colour of background edge |
| back_image | NULL | Image to use for background (NULL for none). See the SVGGraph background image page for details. |
| back_image_width | 100% | Width of background image |
| back_image_height | 100% | Height of background image |
| back_image_opacity | 1.0 | Opacity of background image (0.0-1.0) |
| back_image_top | 0 | Top offset of background image |
| back_image_left | 0 | Left offset of background image |
| back_image_mode | auto | Background image display method. Options are:
|
| pad_top | 10 | Space at top of graph |
| pad_bottom | 10 | Space at bottom of graph |
| pad_left | 10 | Space to left of graph |
| pad_right | 10 | Space to right of graph |
| link_base | | Prepended to all links |
| link_target | _blank | Link target frame |
| namespace | false | Option to use the svg: namespace prefix |
| doctype | false | Option to output the DOCTYPE |
| show_tooltips | true | Enables display of tooltips over graph markers |
| tooltip_colour | black | Tooltip text/border colour |
| tooltip_stroke_width | 1 | Tooltip border thickness |
| tooltip_back_colour | #ffffcc | Tooltip rectangle background colour |
| tooltip_font | sans-serif | Font for tooltips |
| tooltip_font_weight | normal | Tooltip font weight |
| tooltip_font_size | 10 | Tooltip font size |
| tooltip_padding | 3 | Tooltip rectangle padding |
| tooltip_round | 0 | Radius of rounded tooltip corner |
| tooltip_shadow_opacity | 0.3 | Opacity of tooltip shadow (0.0-1.0, 0 disables shadow) |
| tooltip_offset | 10 | Distance between cursor and tooltip |
| compat_events | false | Set to TRUE to fall back to inline event handlers, required by Adobe IE plugin |
For details of the options specific to each type of graph, please visit the relevant page:
For more examples and explanations, take a look at the background image page and the axis and grid dimensions page.
