[ Index ] [ Graphite classes ] [ Graphite elements ] [ All elements ]

Class Graphite_GraphBuilder

Graphite graph query string generator.

DSL and ini file driven API to assist in generating Graphite graph query strings.

Example:

  1. <?php
  2. /**
  3.  * Example usage of the DSL API to construct a graph of memory usage.
  4.  */
  5.  
  6. require_once dirname(__FILE__) . '/../src/autoload.php';
  7.  
  8. $g = Graphite_GraphBuilder::builder()
  9.     ->title('Memory')
  10.     ->vtitle('Mbytes')
  11.     ->width(800)
  12.     ->height(600)
  13.     ->bgcolor('white')
  14.     ->fgcolor('black')
  15.     ->from('-2days')
  16.     ->area('stacked')
  17.     ->prefix('collectd')
  18.     ->prefix('com.example.host')
  19.     ->prefix('snmp')
  20.     ->series('memory-free', array(
  21.         'cactistyle' => true,
  22.         'color' => '00c000',
  23.         'alias' => 'Free',
  24.         'scale' => '0.00000095367',
  25.       ))
  26.     ->series('memory-used', array(
  27.         'cactistyle' => true,
  28.         'color' => 'c00000',
  29.         'alias' => 'Used',
  30.         'scale' => '0.00000095367',
  31.       ))
  32.     ;
  33. ?>
  34. <!DOCTYPE html>
  35. <html>
  36.   <head>
  37.     <title></title>
  38.   <head>
  39.   <body>
  40.     <img src="http://graphite.example.com/render?<?php echo $g; ?>">
  41.   </body>
  42. </html>

Author(s):
Copyright:   2012 Bryan Davis and contributors. All Rights Reserved.
Link:   http://readthedocs.org/docs/graphite/en/latest/url-api.html
Link:   http://bd808.com/graphite-graph-php/
Link:   http://graphite.wikidot.com/
License:   Simplified BSD License

Member Variables

protected array $meta = array()
Configuration metadata.

Metadata is arbitrary configuration data that may be used in creating a graph but is not directly graph settings or rendered targets. Examples include ini-file prefix configurations and abstract series.

The top level array is keyed on category. Each category is expected to be an array of name => data pairs. The format of the data is category specific.
protected array $prefixStack
Series prefix stack.
protected array $settings
Graph settings.
protected array $targets
Configuration for each target that will be rendered or retrieved.

Method Summary

public static void builder( [ $settings = null] )
Builder factory.
public static string qsEncode( $str )
Query string specific uri encoding.
public Graphite_GraphBuilder __construct( [ $settings = null] )
Constructor.
public string build( [ $format = null] )
Generate a graphite graph description query string.
public Graphite_Graph_Series buildSeries( $name )
Add a data series to the graph using the Graphite_Graph_Series fluent builder DSL.
public string currentPrefix( )
Get the current target prefix.
public Graphite_GraphBuilder endPrefix( )
End prefix block.
public Graphite_GraphBuilder forecast( $name , $opts )
Add forecast, confidence bands, aberrations and base series using the Holt-Winters Confidence Band prediction model.
public mixed getMeta( $type , $name , [ $default = array()] )
Get metadata by type and name.
public Graphite_GraphBuilder ini( $file , [ $vars = null] )
Load a graph description file.
public Graphite_GraphBuilder line( $opts )
Draws a straight line on the graph.
public string lookupPrefix( $name )
Lookup a prefix in this graph's metadata.
public Graphite_GraphBuilder metric( $name , [ $opts = array()] )
Add a data series to the graph.
public Graphite_GraphBuilder prefix( $prefix )
Set a prefix to add to subsequent series.
public void qs( [ $format = null] )
Alias for build().
public Graphite_GraphBuilder reset( [ $settings = null] )
Reset builder to empty state.
protected string resolvePrefix( $meta )
Resolve a prefix.
public Graphite_GraphBuilder series( $name , [ $opts = array()] )
Add a data series to the graph.
public void storeMeta( $type , $name , $data )
Add new metadata.
public void url( [ $format = null] )
Alias for build().
public mixed __call( $name , $args )
Handle attempts to call non-existant methods.
public mixed __get( $name )
Handle attempts to read from non-existant members.
public void __set( $name , $val )
Handle attempts to write to non-existant members.
public string __toString( )
Convert to string.

Methods

builder

static void builder( [array $settings = null] )

Builder factory.

Parameters:

Name Type Description
$settings array Default settings for graph

qsEncode

static string qsEncode( string $str )

Query string specific uri encoding.

Per RFC-3986: URI producing applications should percent-encode data octets that correspond to characters in the reserved set unless these characters are specifically allowed by the URI scheme to represent data in that component.

Php's builtin urlencode function is a general purpose encoder. This means that it takes the most conservative approach to encoding. It percent-encodes all octets that are not in the "unreserved" set (ALPHA / DIGIT / "-" / "." / "_" / "~"). Actually it goes further than this and encodes the tilde as well for no apparent reason other than potential binary compatibility with the output of early non-conforming user-agents.

Within the "query" section of a URI there is a broader set of valid characters allowed without percent-encoding:

  • query = *( pchar / "/" / "?" )
  • pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
  • unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
  • pct-encoded = "%" HEXDIG HEXDIG
  • sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
This encoder will let php do the heavy lifting with urlencode() but will then decode _most_ query allowed characters. We will leave "&", "=", ";" and "+" percent-encoded to preserve delimiters used in the application/x-www-form-urlencoded encoding.

What's the point? I could claim that it reduces the size of the encoded string, but my real reason is that it makes the Graphite query strings more readable for debugging.

Parameters:

Name Type Description
$str string String to encode for embedding in the query component of a URI.

__construct

Graphite_GraphBuilder __construct( [array $settings = null] )

Constructor.

Parameters:

Name Type Description
$settings array Default settings for graph

build

string build( [string $format = null] )

Generate a graphite graph description query string.

Parameters:

Name Type Description
$format string Format to export data in (null for graph)

Exceptions:

Type Description
Graphite_ConfigurationException If required data is missing

buildSeries

Graphite_Graph_Series buildSeries( string $name )

Add a data series to the graph using the Graphite_Graph_Series fluent builder DSL.

Parameters:

Name Type Description
$name string Name of data series to graph

currentPrefix

string currentPrefix( )

Get the current target prefix.

endPrefix

Graphite_GraphBuilder endPrefix( )

End prefix block.

forecast

Graphite_GraphBuilder forecast( $name , array $opts )

Add forecast, confidence bands, aberrations and base series using the Holt-Winters Confidence Band prediction model.

Parameters:

Name Type Description
$opts array Line options
$name

Exceptions:

Type Description
Graphite_ConfigurationException If required options are missing

getMeta

mixed getMeta( string $type , string $name , [mixed $default = array()] )

Get metadata by type and name.

Parameters:

Name Type Description
$type string Metadata type
$name string Configuration name
$default mixed Data to return if no matching metadata is found

ini

Graphite_GraphBuilder ini( string $file , [array $vars = null] )

Load a graph description file.

Parameters:

Name Type Description
$file string Path to file
$vars array Variables to substitute in the ini file

line

Graphite_GraphBuilder line( array $opts )

Draws a straight line on the graph.

Parameters:

Name Type Description
$opts array Line options

Exceptions:

Type Description
Graphite_ConfigurationException If required options are missing

lookupPrefix

string lookupPrefix( string $name )

Lookup a prefix in this graph's metadata.

Parameters:

Name Type Description
$name string Prefix name

metric

Graphite_GraphBuilder metric( string $name , [array $opts = array()] )

Add a data series to the graph.

Parameters:

Name Type Description
$name string Name of data series to graph
$opts array Series options

prefix

Graphite_GraphBuilder prefix( string $prefix )

Set a prefix to add to subsequent series.

Parameters:

Name Type Description
$prefix string Prefix to add

qs

void qs( [ $format = null] )

Alias for build().

Parameters:

Name Type Description
$format

reset

Graphite_GraphBuilder reset( [array $settings = null] )

Reset builder to empty state.

Parameters:

Name Type Description
$settings array Default settings for graph

resolvePrefix

string resolvePrefix( mixed $meta )

Resolve a prefix.

Parameters:

Name Type Description
$meta mixed Scalar prefix value or array of prefix configuration

series

Graphite_GraphBuilder series( string $name , [array $opts = array()] )

Add a data series to the graph.

Parameters:

Name Type Description
$name string Name of data series to graph
$opts array Series options

storeMeta

void storeMeta( string $type , string $name , mixed $data )

Add new metadata.

Parameters:

Name Type Description
$type string Metadata type
$name string Configuration name
$data mixed Metadata

url

void url( [ $format = null] )

Alias for build().

Parameters:

Name Type Description
$format

__call

mixed __call( string $name , array $args )

Handle attempts to call non-existant methods.

Looks for $name in settings and gets/sets value if found. If the setting isn't valid an E_USER_NOTICE warning will be raised.

Parameters:

Name Type Description
$name string Method name
$args array Invocation arguments

__get

mixed __get( string $name )

Handle attempts to read from non-existant members.

Looks for $name in settings and returns value if found. If the setting isn't valid an E_USER_NOTICE warning will be raised.

Parameters:

Name Type Description
$name string Setting name

__set

void __set( string $name , mixed $val )

Handle attempts to write to non-existant members.

Sets setting $name=$val if $name is a valid setting. If the setting isn't valid an E_USER_NOTICE warning will be raised.

Parameters:

Name Type Description
$name string Member name
$val mixed Value to set

__toString

string __toString( )

Convert to string.

Located in /src/Graphite/GraphBuilder.php [line 26]