Epguides.com Zend Framework API

Lately I have been writing Service API’s for Zext, my Zend Framework library extension. I plan on publishing some of the more useful ones over the next couple of months on my blog. The first of the series is the Epguides.com API.

Epguides.com is a listing of TV show episode listings. This can be useful, for example, if you are downloading episodes from the internet and want to automatically name the files. Alternatively, if you are hosting a website this API could expose current episode listings for shows of your choice.

The API consists of three parts:

  1. Zext_Service_Epguides – The basic service class. Has one public method: getShowObject($showName)
  2. Zext_Service_Epguides_Show – The objet that is returned by getShowObject($showName)
  3. Zext_Service_Epguides_Episode – Individual episode objects that reside in the show object

Zext_Service_Epguides

Fortunately, Epguides.com has a very regular naming scheme for their pages. The basic pattern is http://epguides.com/{_show_name_}/ where show_name is the name of the show, in lowercase, with whitespace and special characters removed. This can be accomplished using the following regex:

$showName = strtolower(preg_replace('/[^\w]/', '', $showName));

Rather unfortunately, epguides.com doesn’t follow this naming scheme for all shows. For example, “The Office” (North American Version) is called “office_us”. Therefore, when querying epguides.com using this API you want to be using the string that identifies the proper URL of the desired show. The API will generate the correct URL for shows that conform to the regular naming scheme, but you must use the epguides.com naming conventions for show names that are exceptions to the rules.

After the API generates the URL for a given show, it fetches the corresponding page from Epguides.com and parses it. The parsing is done by a combination of domnode selection using the DOMDocument object and regular expressions. Fell free to read the source for more details.

The parser returns an array which is then passed to the Zext_Service_Epguides_Show() object.

The Show and episode classes are fairly straight forward and mostly act as containers to provide some convenience functions. I hope you can get a fairly good idea of how to work with them by viewing the below usage example.

Example Usage

$epguidesAPI = new Zext_Service_Epguides();

//Gets a show object for The Office
$show = $epguidesAPI->getShowObject('office_us');

//Print out all the episodes as strings.
foreach($show->getAllEpisodes() as $episode){
    echo $episode . "\n";
}

//Get the 10th episode of the 2nd season
$episode = $show->getEpisode(2,10);

Download and Install

Download the following file:

Zext_Service_Epguides

Add it to your library path (same folder that Zend of the Zend framework resides in) if you have autoloading enabled.

I will try to respond to any problems in the comments.