Muschamp Rd

How to make a web mashup

December 31st, 2010
CD covers

Or at least how I made several web mashups using PHP and various APIs. I should have written this post sooner and I should have created my latest greatest mashup sooner, now I’ll really get to see how well I documented my code.

UPDATE: I still think these instructions are sufficient, but the latest available version of my code is in a GitHub Repository and the official home for the web mashups I made is this web page.

First a warning, I’m not a big fan of PHP, I’m not a PHP expert, this is the first large-ish collection of PHP I’ve written and probably will ever write. I chose after much frustration with other people’s code to make my own class to represent a collection of music. It works just like a milk carton crate of albums. You can look at the first album easily, you can look at the last album easily, and you can randomly look at any album then the one in front of it or behind it easily. In computer science terms I made my underlying datatype a linked list, even more snazzy I made it a circular linked list. You don’t actually need to know any of this to make a mashup, you do need to know some PHP, you need a webhost which supports PHP 5.0 and some other libraries installed and you need to carefully follow other people’s instructions before you can hope to use my code.

Step One: and Amazon

You need to get APIs to work on your server, the first two I worked with and recommend because they offer lots of information and images is Amazon Product API and Both have PHP code available showing you how to do basic and advanced stuff.

If you can’t get Sameer’s and Matt’s code to work, you have no hope of getting my code to work as I rely on Sameer’s and Matt’s code. You’ll also need to apply for API keys from LastFM and Amazon.

Now you should be able to build something that looks like this, but it’ll be a lot easier using my code.

Step Two: More APIs

Although you can make a mashup with just two APIs I went whole hog when making my PHP code base so I got Facebook integration to work using Vadim’s code. So now you need to follow his instructions and get that codebase to work too. I don’t make much use of it, but the support is there in my code to use his entire library.

Another music API out there is MusicBrainz, I don’t find it that great, but I did add support for it in my class. Not wanting to re-invent the wheel I used PHPBrainz, you should look into getting it to work too. I can’t recommend this codebase or API that highly, but when all else fails sometimes it has the information I’m looking for.

Step Three: PHP I modified

In order to make the mashup(s) I imagined it proved necessary to add methods to both Matt’s and Sameer’s code. One thing I implemented was keeping all the API keys in an external file as constants which I called myInfo.php. So now you need to download my versions of Matt’s and Sameer’s code, make sure they still work, and start moving your API keys to myInfo.php.

  1. Matt’s LastFM API code which I modified
  2. Sameer’s Amazon API PHP code which I modified
  3. Sample myInfo.php

I copied all these from my live website on December 30th 2010.

Step Four: Helper Code

I’m not a PHP guy, so things I expected to be able to do like have multiple constructors, I learned to my dismay I couldn’t. I also learned that you need to write your own little helper functions sometimes to save yourself typing things over and over.

If you find yourself typing something over and over you need to refactor or at least review your code. A better way probably exists. I put my little helper functions in muskLib.php which you’ll need to download.

Step Five: Caching

If you plan on fetching a lot of information, especially images from various APIs you’ll need to implement caching or your performance will suck. I’m no caching expert but I had to implement two different basic caching methods for Objects and Arrays. I wish everything was either an Object or an Array but different APIs have different ideas or at least their authors do.

So you’ll need to create a directory below where your mashup will be called “AlbumCollectionCache” and inside that I recommend you create the following five subdirectories: Amazon, Flickr, iTunes, LastFM, and MusicBrainz. And if you haven’t guessed already I got yet more APIs working, but I didn’t rely on other people’s code as much, tired of fixing other people’s bugs and shortcomings. You will need to download caching.php.

Step Six: albumCollection.php

This is the class that I put all the effort into building which does all the work in my music mashups. It is called album collection because there was a time when people collected albums. I realize a lot of people pirate their music or at least think in terms of songs or tracks and I decided to make one last mashup that took a song centric point of view. To that end you can make a subclass (or parent class) of albumCollection.php called say musicCollection.php which I plan to work on further, but first I wanted to document and I guess release or at least make available more easily the PHP code I slaved over.

This copy of albumCollection.php is from December 30th 2010.

Now you should be able to make a mashup like this one or you can just read about it, if you want to learn a littler more about how it was made and the code used.

Step Seven: Getting your music into albumCollection.php

My album collection was in a text file, so I created my PHP class around reading in the raw data from .csv file. I wanted to have multiple constructors, but the only one I’ve written and tested is reading in a list of artist and album titles. Here is some token test data to get you started.

I plan to work more on a subclass and on my class constructor further. This will provide other options to create an instance of the class.

Step Eight: Simple Test Album Cover Gallery

Results of sample code
Although my code base does, way, way more. I made lots of proof of concept type tests, a very simple one which you can try now consists of three lines of PHP. You need to create a new file called testGallery.php or something similar. It has to be in the same directory as albumCollection.php and all the other code as well as myInfo.php which also has to be in that directory or below. After you get this basic gallery to work you can start modifying things.

$myAlbumCollection = new albumCollection("testGallery.csv");

The results of running this along with a bit of CSS can be seen here.

Step Nine: To Infinity and Beyond

There you’ve created a token mashup, hopefully you can think of a better use for mine and other people’s code. One last API or web service I decided to get working was Flickr using phpFlickr. I have this in my subclass which I plan to expand and test some more. I even hope to get the alternate constructor idea working…

My code should be fairly well documented and tested, but it is what it is, some PHP code you downloaded off the Internet written by someone who doesn’t even like PHP.

Don’t claim it as your own. Don’t sell it or use it as part of a commercial project without permission. phpBrainz has the strictest licensing agreement, but it isn’t crucial so I may drop support for it eventually, so in order to use my code you need to satisfy the requirements of the phpBrainz author because I incorporated calls to his methods into albumCollection.php but they are easy enough to remove, if you don’t need to use that web service in your mashup.

Step Ten: Use the latest version of my PHP mashup codebase

I refactored and updated my PHP code creating an even more versatile hierarchy of classes.  All my mashups were converted to work with the new classes and I may add a few more APIs and create yet more subclasses.  If you gotten this far and wish to use the latest greatest classes and methods, my code is linked to from this webpage.

Posts on Muskblog © Andrew "Muskie" McKay comments not necessarily so...
CFA Institute does not endorse, promote or warrant the accuracy or quality of Muskblog. CFA® and Chartered Financial Analyst® are registered trademarks owned by CFA Institute.