Spinitron API demo in PHP

Source code for this demo web site is on Github

This page shows how to use the Spinitron v2 API in a web page using PHP directly and with JavaScript and Ajax to update a page automatically from the browser.

For integration of content from Spinitron using iframe and JavaScript widgets see the v2 Web Intragration Demo

In the yellow box, the recent spins and upcoming shows use API data. When the server generates this page, it renders two PHP partial views, recent.php and today.php. These fetch data from the API and render it as HTML. Additionally, a client-side JavaScript refreshes the recent spins every five seconds with an Ajax request to recent.php.

Overview

The files in this demo are organized as follows:

├── app
│   ├── getClient.php
│   └── SpinitronApiClient.php
├── cache
└── www
    ├── css
    ├── index.php
    ├── recent.php
    └── today.php

• app has a simple caching client class for the Spinitron v2 API and a script that instantiates it with your API key.
• cache holds the temporary cache data files.
• www has this page and the two partial views recent.php and today.php.

Try it yourself

If you have a computer with PHP, you can run this demo locally and modify it:

• Download and upzip the zip file (or clone the repo)
• Create a file api-key.txt in the root directory (beside the app and www directories) containing your API key, which you can find in the admin area of Spinitron v2
• Open a command shell and in the www directory start a test PHP web server:

  php -S localhost:8000

• Go to http://localhost:8000/ in a browser.

To use this approach in your web site, adapt the examples in the www directory. Make sure the app and cache directories are outside your web server's document root. If you move the app directory relative to www then update the line that includes getClient.php in the partial views.

SpinitronApiClient.php is not complex so if you know PHP, take a look.

How it works

index.php is this page. It is ordinary HTML with only two interesting parts. First, inside the <div class="widget-box"> block are two PHP blocks that render the output of recent.php and today.php into this page as it is loaded. Second, at the bottom of the page is a JavaScript that uses AJAX to replace the content of the <div id="spin-recent"> block every five seconds.

recent.php and today.php are partial views, which means they output fragments of HTML to be placed inside something else. In our case the fragments are put into <div> blocks on this page. Look in recent.php. First it loads the client. Next it uses the client to get data from the API. Finally it uses a PHP foreach loop to generate a number of <p> elements, each containing text describing a recent spin. today.php is very similar.

If you have the test web server running, as described above, you can view the output of these partial views in your browser by navigating to and viewing the page source of the following URLs:

http://localhost:8000/recent.php
http://localhost:8000/today.php

Both partial views use the following line to bootstrap a SpinitronApiClient.

include __DIR__ . '/../app/getClient.php';

getClient.php instantiates a SpinitronApiClient object using your API key and saves it to the global variable $client. It offers simple generic methods search() and fetch() to get data from the API. recent.php loads the most recent three songs with $client->search('spins', ['count' => 3]) and today.php loads the upcoming schedule in a similar way. Read SpinitronApiClient itself for more detail—it's not complex. See also the API documentation.

To summarize

The two partial views recent.php and today.php:

1. include getClient.php, which provides a SpinitronApiClient object,
2. use the client to get data from Spinitron,
3. generate fragments of HTML (to display the data) as output.

The main web page index.php:

1. on initial page load, inserts the HTML fragments output by the partial views into the page using PHP include(),
2. initializes a JavaScript in the client's web browser that to replace the list of recent spins with freshly loaded output of recent.php every five seconds.

Garbage collection

SpinitronApiClient doesn't collect garbage, i.e. it does not delete expired cache files. If, like this demo, all your queries use static parameters, e.g. ['spins', 3] or ['end', '+6 hour'], then you don't need garbage collection since stale cache files will not proliferate. But if your queries have variable parameters, e.g. date-times, then you probably need it.

Searching through cache files to find expired ones can take time so it's good to decouple it from page request processing, which is the only time SpinitronApiClient is used in this demo. So SpinitronApiClient collects cache files together according to their lifetimes. The name of each top level directory in the cache is the expiration time in seconds of the cache files it contains, e.g.

/var/www/v2-api-demo/cache
├── 30
│   └── spins?count=3
└── 900
    └── shows?end=%2B6+hour

This allows other programs to figure which files are expired. For example, I put this in /etc/cron.hourly of the Debian system running this demo (not that the demo actually needs it)

#!/bin/bash

d=/var/www/v2-api-demo/cache
for f in `ls $d`; do
    let m=($f+59)/60
    find "$d/$f" -type f -mmin +$m -delete
done

Caveat

SpinitronApiClient is very basic. It has no dependencies and should work on older versions of PHP. It was designed to demonstrate making API requests and file caching so you could adapt it to your needs. It is not supposed to be a robust API client. Feel free to use it if it works for you but consider also using other API and HTTP clients.

In closing

Spinitron's terms of service require that you have access credentials in order to use the API and that you don't share them with other entities. We also require that you use a cache. This demo uses a file-based cache.

As always, for support contact Eva at Spinitron on 617 233 3115 or by email at eva@spinitron.com.