<?php
/**
rrdtool - php class for interfacing to rrdtool
Version 0.1-alpha
Copyright (C) 2003 Greg MacLellan
Aug 27/2003

greg at mtechsolutions dot ca

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    http://www.gnu.org/licenses/lgpl.html


This is an interface to the excellent RRD Tool (www.rrdtool.com) program written by
Tobi Oetiker.

Yes, I know there is a php4 extension for rrdtool. I wrote this anyways, for a couple
reasons:
- As far as I can tell, the extension is experimental. I don't want to add something
  that's experimental to all php processes.
- I couldn't get the dynamic version to compile, and figured this would take less time
  than messing with it.
- This is a more portable solution, as you just need rrdtool and php, and don't need to
  specifically build the rrdtool extensions.
- These classes can easily be rewritten to use the extension functions, and you still
  get the benefit of OOP.


When called, this class opens a new pipe to rrdtool. Be sure to call rrdtool::close()
when finished. Using a pipe allows you to make multiple UPDATE calls (or whatever)
without using a ton of exec() calls.

Fairly simple. There's some rough examples at the bottom.

- Greg

*/


/** rrdtool functions
 */
class rrdtool {
    var $debug = false;

    var $_pipes;
    var $_proc;

    /** create a new rrdtool handle
     * @param string    $rrdtool_bin    The path to the rrdtool binary
     */
    function rrdtool($rrdtool_bin) {
        $descriptorspec = array(
           0 => array("pipe", "r"),  // stdin is a pipe that the child will read from
           1 => array("pipe", "w"),  // stdout is a pipe that the child will write to
           2 => array("pipe", "w")   // stderr is a pipe that the child will write to
        );

        // proc_open rrdtool, using - as a parameter, to specify "remote control mode"
        $this->_proc = proc_open($rrdtool_bin." -", $descriptorspec, $this->_pipes);
        var_dump($this->_proc);
        var_dump($this->_pipes);
    }

    function close() {
        fclose($this->_pipes[0]);
        fclose($this->_pipes[1]);
        fclose($this->_pipes[2]);
        proc_close($this->_proc);
    }

    function _run($command) {
        fwrite($this->_pipes[0], $command."\n");
        $data = "";
        $line = "";
        while (substr($line,0,2) != "OK") {
            $line = fgets($this->_pipes[1],1024);
            $data .= $line;
        }
        if ($this->debug) {
            var_dump($data);
        }

        // not sure if this is 100% safe or not, according to the docs,
        // it looks like it should be
        return (substr($data,0,5) != "ERROR");
    }

    /** Create a new rra
     * @param string    $filename    Full path and name of the rrd file to create
     * @param int        $start        Start time, timestamp or AT spec (--start)
     * @param int        $step        Step value, in seconds (--step)
     * @param array        $ds        Array of rrdtool_ds objects for specifying
     *                    data sources
     * @param array        $rra        Array of rrdtool_rra objects for specifying
     *                    round-robin archives
     */
    function create($filename, $start, $step, $ds, $rra) {
        $options = array();

        // create DS options string
        foreach ($ds as $rrd_ds) {
            $options[] = "DS:".$rrd_ds->name.":".$rrd_ds->type.":".$rrd_ds->heartbeat.":".$rrd_ds->min.":".$rrd_ds->max;
        }

        // create RRA options string
        foreach ($rra as $rrd_rra) {
            $options[] = "RRA:".$rrd_rra->cf.":".$rrd_rra->xff.":".$rrd_rra->steps.":".$rrd_rra->rows;
        }

        $args = "--step ".$step." ".implode(" ",$options);
        return $this->_run("create ".$filename." ".$args);

    }

    /** Update data in an rra
     * @param string    $filename    Full path and name of the rrd file
     * @param array        $data        Data values. If array keys are specified,
     *                    they should be the DS names, and a template
     *                    will be used (--template).
     * @param int        $time        The update time to use, or null for 'N' (rrdtool
     *                    uses current time)
     */
    function update($filename, $data, $time = null) {
        $args = "";
        if (!isset($data[0])) {
            // assume there are names for all the items, so use a template
            $args .= "-t ".implode(":",array_keys($data))." ";
        }
        $args .= (!empty($time) ? "N" : $time).implode(":",$data);

        return $this->_run("update ".$filename." ".$args);
    }

    /** Create a graph
     * This function can be called either instantized, or statically. If it's an instance,
     * $outputfile must be specified. If called statically, rrdtool is called directly by
     * an exec() system call (not via pipes, like normal), and if $outputfile is null, then
     * the raw image data will be returned, and no image file needs to be created on disk
     *
     * @param array        $options    General options. Should be specified using
     *                    their full option name as a key. For example, to
     *                    set "--upper-limit 10", use
     *                    array("upper-limit"=>10)
     * @param array        $items        An array of items inherited from the rrdtool_graph
     *                    class. Passed as arguments, in the array's order
     * @param string    $outputfile    The graph file to create. Note: If being called
     *                    statically (ie: rrdtool::graph()) then this should
     *                    be the path to the rrdtool binary.
    */
    function graph($options, $items, $outputfile) {
        $args;
        foreach ($options as $name=>$value) {
            $args .= "--".$name." ".$value."  ";
        }

        foreach (array_keys($items) as $key) { // use array_keys to prevent copying
            $args .= $items[$key]->output()." ";
        }

        if (isset($this)) {
            // being called as part of a class, run normally
            return $this->_run("graph ".$args);
        } else {
            // special case: being called statically
            // Note: $args is not necessarily safe for commandline - be careful
            //       with where the input comes from
            exec(escapeshellcmd($outputfile)." ".$args);
        }

    }

    function info($filename) {
        // this was more for testing than anything
        return $this->_run("info ".$filename);
    }
}

/** Data source definition
 */
class rrdtool_ds {
    var $name;
    var $type;
    var $heartbeat;
    var $min;
    var $max;

    function rrdtool_ds($name, $type, $heartbeat, $min = "U", $max = "U") {
        $this->name = $name;
        $this->type = $type;
        $this->heartbeat = $heartbeat;
        $this->min = $min;
        $this->max = $max;
    }
}

/** Round-robin archive definition
 */
class rrdtool_rra {
    var $cf;
    var $steps;
    var $rows;
    var $xff;

    function rrdtool_rra($cf, $steps, $rows, $xff = 0.5) {
        $this->cf = $cf;
        $this->steps = $steps;
        $this->rows = $rows;
        $this->xff = $xff;
    }
}


class rrdtool_graph {
    function output() { //abstract -- children must override this
        return false;
    }
}

class rrdtool_graph_def extends rrdtool_graph {
    var $vname;
    var $rrdfile;
    var $ds;
    var $cf;

    function rrdtool_graph_def($vname, $rrdfile, $ds, $cf) {
        $this->vname = $vname;
        $this->rrdfile = $rrdfile;
        $this->ds = $ds;
        $this->cf = $cf;
    }

    function output() {
        // DEF:vname=rrd:ds-name:CF
        return "DEF:".$this->vname."=".$this->rrdfile.":".$this->ds.":".$this->cf;
    }
}

class rrdtool_graph_cdef extends rrdtool_graph {
    var $vname;
    var $expr;

    function rrdtool_graph_cdef($vname, $expr) {
        $this->vname = $vname;
        $this->expr = $expr;
    }

    function output() {
        // CDEF:vname=rpn-expression
        return "CDEF:".$this->vname."=".$this->expr;
    }
}

class rrdtool_graph_print extends rrdtool_graph {
    var $vname;
    var $cf;
    var $format;

    function rrdtool_graph_print($vname, $cf, $format) {
        $this->vname = $vname;
        $this->cf = $cf;
        $this->format = $format;
    }

    function output() {
        // PRINT:vname:CF:format
        return "PRINT:".$this->vname.":".$this->cf.":".$this->format;
    }
}

class rrdtool_graph_gprint extends rrdtool_graph {
    var $vname;
    var $cf;
    var $format;

    function rrdtool_graph_gprint($vname, $cf, $format) {
        $this->vname = $vname;
        $this->cf = $cf;
        $this->format = $format;
    }

    function output() {
        // GPRINT:vname:CF:format
        return "GPRINT:".$this->vname.":".$this->cf.":".$this->format;
    }
}

class rrdtool_graph_comment extends rrdtool_graph {
    var $text;

    function rrdtool_graph_comment($text) {
        $this->text = $text;
    }

    function output() {
        // COMMENT:text
        return "COMMENT:".escapeshellarg($this->text);
    }
}

class rrdtool_graph_hrule extends rrdtool_graph {
    var $value;
    var $color;
    var $legend;

    function rrdtool_graph_hrule($value, $color, $legend = false) {
        $this->value = $value;
        $this->color = $color; // in "rrggbb" hex format
        $this->legend = $legend;
    }

    function output() {
        // HRULE:value#rrggbb[:legend]
        return "HRULE:".$this->value."#".$this->color.(!empty($this->legend) ? ":".escapeshellarg($this->legend) : "");
    }
}

class rrdtool_graph_vrule extends rrdtool_graph {
    var $value;
    var $color;
    var $legend;

    function rrdtool_graph_vrule($value, $color, $legend = false) {
        $this->value = $value;
        $this->color = $color; // in "rrggbb" hex format
        $this->legend = $legend;
    }

    function output() {
        // VRULE:value#rrggbb[:legend]
        return "VRULE:".$this->value."#".$this->color.(!empty($this->legend) ? ":".escapeshellarg($this->legend) : "");
    }
}

class rrdtool_graph_line extends rrdtool_graph {
    var $type;
    var $value;
    var $color;
    var $legend;

    function rrdtool_graph_line($type, $vname, $color = false, $legend = false) {
        $this->type = $type;
        $this->value = $value;
        $this->color = $color; // in "rrggbb" hex format
        $this->legend = $legend;
    }

    function output() {
        // LINE{1|2|3}:vname[#rrggbb[:legend]]
        return "LINE".$this->type.":".$this->value.(!empty($this->color) ? "#".$this->color : "").(!empty($this->legend) ? ":".escapeshellarg($this->legend) : "");
    }
}

class rrdtool_graph_area extends rrdtool_graph {
    var $vname;
    var $color;
    var $legend;

    function rrdtool_graph_area($vname, $color, $legend = false) {
        $this->vname = $vname;
        $this->color = $color; // in "rrggbb" hex format
        $this->legend = $legend;
    }

    function output() {
        // AREA:vname#rrggbb[:legend]
        return "AREA:".$this->vname."#".$this->color.(!empty($this->legend) ? ":".escapeshellarg($this->legend) : "");
    }
}

class rrdtool_graph_stack extends rrdtool_graph {
    var $vname;
    var $color;
    var $legend;

    function rrdtool_graph_stack($vname, $color, $legend = false) {
        $this->vname = $vname;
        $this->color = $color; // in "rrggbb" hex format
        $this->legend = $legend;
    }

    function output() {
        // STACK:vname#rrggbb[:legend]
        return "STACK:".$this->vname."#".$this->color.(!empty($this->legend) ? ":".escapeshellarg($this->legend) : "");
    }
}


/** Examples:


Update a couple files:

    $rrd = new rrdtool("/usr/local/rrdtool/bin/rrdtool");
    $rrd->update("/path/to/rra/cisternlevel_16.rrd", array(45));
    $rrd->update("/path/to/rra/wellcurrent_17.rrd", array("ds1"=>7,"ds2"=>12));
    $rrd->close();



Generate a graph:

    $options = array(
            "title"=>"Demo Graph",
            "imgformat"=>"PNG"
        );
    $items = array(
            new rrdtool_graph_def("bps-in","bps_router1.rrd","bps-in","AVERAGE"),
            new rrdtool_graph_def("bps-out","bps_router1.rrd","bps-out","AVERAGE"),
            new rrdtool_graph_line("bps-in","0000FF","Traffic out"),
            new rrdtool_graph_area("bps-out","00FF00","Traffic in")
        );

    header("Content-type: image/png");
    echo rrdtool::graph($options, $items);

*/
?>