Using the RESTful API via PHP

There are two APIs you can use to manipulate the Holiday: the RESTful API, which has a bunch of methods or the SecretAPI, which uses crafted UDP packages to paint colours onto the Holiday light string directly. While the RESTful API has more functionality, the SecretAPI is much, much faster.

You can find a PHP class library to access the Holiday via the RESTful API at https://github.com/Djelibeybi/PHP-HolidayAPI. The GIT repository includes some sample scripts that use the class library.

Bug reports, pull requests, comments welcome.

Currently, the following methods are defined:

setglobe($globenum, $r, $g, $b)

Sets the globe with number $globenum (base 0 to 49) to the colour represented by $r, $g and $b.

fill($r, $g, $b)

Fills the entire string, i.e. all globes, with the same colour represented by $r, $g and $b.

getglobe($globenum)

Returns an array of the RGB colour values for the globe with the number $globenum as represented internally within the object. Note that the SecretAPI doesn’t have a query mechanism, so we can’t actually retrieve the currently active value for the globe. This is the value we think the globe is.

render()

This submits a JSON-encoded query to the RESTful API and paints the current state of the globes onto the Holiday. Used after calling fill() or setglobe() to paint the values onto the light(s).

The functions above are the base building blocks you can use to paint almost anything onto the Holiday string. However, there are also some pre-defined animations that can be accessed directly via the RESTful API. The first (and currently only) method implemented is for the Gradient API:

gradient($begin, $end, $steps)

Automatically animates a gradient between the RGB colour represented by the $start array and the $end array using $steps per second. The gradient method will automatically start the animation and return once the gradient has finished animating. If you call the render() method after using the gradient() method, it will repaint the previous state of the lights back onto the string.