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: auto image will be uniformly scaled to fit in width and height; tile image will be tiled in blocks using width and height; stretch image will be stretched to fit width and height
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

Global options

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.