Recent spins
9:29am Breanna Barbara “Diamond Light” from Nothin' but Time
9:24am Pere Ubu “Beach Boys” from Raygun Suitcase
9:21am rauchen “Reaktion” from EP III - EP
(Updated 13:29:47 UTC)
Coming up later today
8:00am Infernal Racket
10:00am Ignore the Machine
12:00pm Democracy Now!
1:00pm Patchwork
2:00pm Cherry Vanilla Broke
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 viewsrecent.php
andtoday.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 theapp
andwww
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
:
- include
getClient.php
, which provides aSpinitronApiClient
object, - use the client to get data from Spinitron,
- generate fragments of HTML (to display the data) as output.
The main web page index.php
:
- on initial page load, inserts the HTML fragments output by the partial views into the page using PHP
include()
, - 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.