carlosbuenosvinos / php-geckoboard-api

A PHP library for pushing data into Geckoboard custom widgets

CarlosIO\Geckoboard

A PHP library for pushing data into Geckoboard custom widgets (http://www.geckoboard.com/developers/custom-widgets/widget-types)

Installation

The best way to install the library is by using Composer. Add the following to composer.json in the root of your project:

{
    "require": {
        "carlosio/geckoboard": "1.*"
    }
}

Then, on the command line:

curl -s http://getcomposer.org/installer | php
php composer.phar install

Use the generated vendor/autoload.php file to autoload the library classes.

Usage

require __DIR__ . '/vendor/autoload.php';

use CarlosIO\Geckoboard\Widgets\NumberAndSecondaryStat;
use CarlosIO\Geckoboard\Client;

$widget = new NumberAndSecondaryStat();
$widget->setId('<your widget id>');
$widget->setMainValue(123);
$widget->setSecondaryValue(238);
$widget->setMainPrefix('EUR');

$geckoboardClient = new Client();
$geckoboardClient->setApiKey('<your token>');
$geckoboardClient->push($widget);

Widget: Number and optional secondary stat

use CarlosIO\Geckoboard\Widgets\NumberAndSecondaryStat;
use CarlosIO\Geckoboard\Client;

$widget = new NumberAndSecondaryStat();
$widget->setId('<your widget id>');
$widget->setMainValue(123);
$widget->setSecondaryValue(238);
$widget->setMainPrefix('EUR');

$geckoboardClient = new Client();
$geckoboardClient->setApiKey('<your token>');
$geckoboardClient->push($widget);

Widget: RAG numbers only

use CarlosIO\Geckoboard\Data\Entry;
use CarlosIO\Geckoboard\Widgets\RagNumbers;
use CarlosIO\Geckoboard\Client;

$widget = new RagNumbers();
$widget->setId('<your widget id>');

$redData = new Entry();
$redData->setValue(132)->setText('This is the red description');
$widget->setRedData($redData);

$amberData = new Entry();
$amberData->setValue(134)->setText('This is the amber description');
$widget->setAmberData($amberData);

$greenData = new Entry();
$greenData->setValue(34)->setText('This is the green description');
$widget->setGreenData($greenData);

$geckoboardClient->push($widget);

Widget: RAG column and numbers

use CarlosIO\Geckoboard\Data\Entry;
use CarlosIO\Geckoboard\Widgets\RagColumnAndNumbers;
use CarlosIO\Geckoboard\Client;

$widget = new RagColumnAndNumbers();
$widget->setId('<your widget id>');

$redData = new Entry();
$redData->setValue(132)->setText('This is the red description');
$widget->setRedData($redData);

$amberData = new Entry();
$amberData->setValue(13)->setText('This is the amber description');
$widget->setAmberData($amberData);

$greenData = new Entry();
$greenData->setValue(3)->setText('This is the green description');
$widget->setGreenData($greenData);

$geckoboardClient->push($widget);

Widget: Text

use CarlosIO\Geckoboard\Widgets\Text;
use CarlosIO\Geckoboard\Data\Text\Item;
use CarlosIO\Geckoboard\Client;

$widget = new Text();
$widget->setId('<your widget id>');

$firstItem = new Item();
$secondItem = new Item();

$firstItem->setText('Test message 1');

$secondItem->setText('Test message 2');
$secondItem->setType(Item::TYPE_ALERT);

$widget->addItem($firstItem);
$widget->addItem($secondItem);

$geckoboardClient->push($widget);

Widget: Funnel

use CarlosIO\Geckoboard\Data\Funnel\Entry;
use CarlosIO\Geckoboard\Widgets\Funnel;

$widget = new Funnel();
$widget->setId('<your widget id>');
$widget->setType('reversed');
$widget->setShowPercentage(false);

$error = new Entry();
$error->setLabel('Step 1')->setValue(87809);
$widget->addEntry($error);

$error = new Entry();
$error->setLabel('Step 2')->setValue(70022);
$widget->addEntry($error);

$error = new Entry();
$error->setLabel('Step 3')->setValue(63232);
$widget->addEntry($error);

$error = new Entry();
$error->setLabel('Step 4')->setValue(53232);
$widget->addEntry($error);

$error = new Entry();
$error->setLabel('Step 5')->setValue(32123);
$widget->addEntry($error);

$error = new Entry();
$error->setLabel('Step 6')->setValue(23232);
$widget->addEntry($error);

$error = new Entry();
$error->setLabel('Step 7')->setValue(12232);
$widget->addEntry($error);

$error = new Entry();
$error->setLabel('Step 8')->setValue(2323);
$widget->addEntry($error);

$geckoboardClient->push($widget);

Widget: PieChart

use CarlosIO\Geckoboard\Data\PieChart\Entry;
use CarlosIO\Geckoboard\Widgets\PieChart;

$widget = new PieChart();
$widget->setId('<your widget id>');

$entry = new Entry();
$entry->setLabel('May')->setValue(100)->setColor('ffff10');
$widget->addEntry($entry);

$entry = new Entry();
$entry->setLabel('June')->setValue(160)->setColor('ffaa0a');
$widget->addEntry($entry);

$entry = new Entry();
$entry->setLabel('July')->setValue(300)->setColor('ff5505');
$widget->addEntry($entry);

$entry = new Entry();
$entry->setLabel('August')->setValue(140)->setColor('ff0000');
$widget->addEntry($entry);

$geckoboardClient->push($widget);

Widget: Geck-o-Meter

use CarlosIO\Geckoboard\Data\Entry;
use CarlosIO\Geckoboard\Widgets\GeckoMeter;

$widget = new GeckoMeter();
$widget->setId('<your widget id>');

$widget->setMinData((new Entry())->setValue(0));
$widget->setMaxData((new Entry())->setValue(100));
$widget->setValue($data);

$geckoboardClient->push($widget);

Widget: Map

use CarlosIO\Geckoboard\Data\Point;
use CarlosIO\Geckoboard\Widgets\Map;

$widget = new Map();
$widget->setId('<your widget id>');

$point = new Point();
$point->setSize(10)->setColor('FF0000')->setLatitude('40.416775')->setLongitude('-3.70379');
$widget->addPoint($point);

$geckoboardClient->push($widget);

Widget: LineChart

use CarlosIO\Geckoboard\Widgets\LineChart;

$widget = new LineChart();
$widget->setId('<your widget id>');
$widget->setItems(array(1, 1.23));
$widget->setColour("ff0000");
$widget->setAxis(LineChart::DIMENSION_X, array("min", "max"));
$widget->setAxis(LineChart::DIMENSION_Y, array("bottom", "top"));

$geckoboardClient->push($widget);

Widget: List

use CarlosIO\Geckoboard\Data\ItemList\Label;
use CarlosIO\Geckoboard\Data\ItemList\Title;
use CarlosIO\Geckoboard\Widgets\ItemList;

$widget = new ItemList();
$widget->setId('<your widget id>');

$title = new Title();
$title->setText("Title text");
$title->setHighlight(true);

$title2 = new Title();
$title2->setText("Title2 text");
$title2->setHighlight(false);

$label = new Label();
$label->setName("Label name");
$label->setColor("red");

$label2 = new Label();
$label2->setName("Label2 name");
$label2->setColor("blue");

$widget->addItem($title, $label, 'description1');
$widget->addItem($title2, $label2, 'description2');

$geckoboardClient->push($widget);

Widget: Monitoring

$widget = (new Monitoring())
    ->setId('<your widget id>')
    ->setStatus('Up')
    ->setDownTime('3 days ago')
    ->setResponseTime('100 ms');

$geckoboardClient()->push($widget);

Widget: LeaderBoard

$widget = new LeaderBoard();
$widget->setId('<your widget id>')

$item = new Item();
$item->setLabel("Title text")
    ->setValue(10)
    ->setPreviousRank(2);
$widget->addItem($item);

$item = new Item();
$item->setLabel("Title text 2")
    ->setValue(7)
    ->setPreviousRank(1);
$widget->addItem($item);

$geckoboardClient()->push($widget);

Push more than one widget at the same time

$widgets = array();
$widget = new LineChart();
// Fill your line chart...
$widgets[] = $widget;

$widget = new Map();
// Fill your map...
$widgets[] = $widget;

$geckoboardClient->push($widgets);

Set timeout for pushing widgets

Use setGuzzleConfig() to pass config options directly to Guzzle.

$geckoboardClient = new Client();
$geckoboardClient->setApiKey('<your token>');
$geckoboardClient->setGuzzleConfig(array('timeout' => 30, 'connect_timeout' => 3));
$geckoboardClient->push($widget);

Testing

In order to run the test, install all dependencies: php composer.phar install

$ bin/phpunit --coverage-text

php-geckoboard-api's Issues

Enhancement Request for Number & 2nd Stat Widget

I have another request for the Num & 2nd Stat widget:

If $secondaryValue has not been set it would be great if null or "" is passed as the value.

Right now it gets set to 0 (intval of null). If 0 is sent then geckboard will calculate the % difference and list it as a 100% increase. In my cases, I'd like the % increase to not be included at all if secondary value is null.

Let me know if you have any questions.

Thanks,

Dan

[status code] 400 [reason phrase] Bad Request

After following the installation process in the README, copying and pasting the first widget code and replacing the Widget ID and API key with accurate values, I run my script and receive the following:

PHP Fatal error:  Uncaught exception 'Guzzle\Http\Exception\ClientErrorResponseException' with message 'Client error response
[status code] 400
[reason phrase] Bad Request

Bullet Measurement should be Measure

Thanks so much for putting this package together.

I found one thing that I believe needs to be changed in \Data\Bullet\Item.php

toArray() should use the key 'measure' instead of 'measurement'

Let me know if you have any questions.

Thanks!

updated docs

hey carlos, thanks for the nice work!

Was wondering if you can provide some additional docs, in the README, for the widgets that are implemented but not documented (ie. line charts).

Support for LeaderBoard optional parameters

Hey,

First off, this is a very useful library, so thank you for writing it!

I was wondering you would be able to add support for a couple of optional parameters on the LeaderBoard widget?

According to the Geckoboard API Docs you can optionally supply format and unit parameters:

https://developer.geckoboard.com/#parameters-10

It would be great to be able to do something like this:

$widget = new LeaderBoard();

$widget->setId( $widget_id );

$widget->setFormat('currency');

$widget->setUnit('GBP');

...

Thanks in advance.

Missing "Monitoring" Widget

Hi,

there seems to be missing the "monitoring" Widget (https://developer.geckoboard.com/#monitoring)

Would it be possible to have it ?

Cheers !

Plans to upgrade Guzzle from 3 to 6?

Hi,

Is there any plans on upgrading this library from Guzzle 3 to Guzzle 6?

Guzzle 3 is very very old and will from my experience not work (at all) with PHP versions newer than 7.0. And the lifetime of PHP 7.0 is coming to it's end quite soon: http://php.net/supported-versions.php

This lib is also the most downloaded geckoboard library on packagist, so it's probably worth upgrading it to work with supported versions of PHP (as of december): https://packagist.org/?query=geckoboard

Unless the project is abandoned, but I don't see any mentions of that (as in huge titles on top of the readme or so).

Can't install with guzzle 3.9.1

• Installation request for carlosio/geckoboard 1.0.5 -> satisfiable by carlosio/geckoboard[1.0.5].
  • Conclusion: remove guzzle/guzzle v3.9.1
  • carlosio/geckoboard 1.0.5 requires guzzle/guzzle 3.7.* -> satisfiable by guzzle/guzzle[v3.7.0, v3.7.1, v3.7.2, v3.7.3, v3.7.4].
  • Can only install one of: guzzle/guzzle[v3.9.1, v3.7.0].
  • Can only install one of: guzzle/guzzle[v3.9.1, v3.7.1].
  • Can only install one of: guzzle/guzzle[v3.9.1, v3.7.2].
  • Can only install one of: guzzle/guzzle[v3.9.1, v3.7.3].
  • Can only install one of: guzzle/guzzle[v3.9.1, v3.7.4].
  • Installation request for guzzle/guzzle == 3.9.1.0 -> satisfiable by guzzle/guzzle[v3.9.1].