Pros:

• Tons of features.
• Support for photo and video uploads.
• Location awareness.
• A good looking and readable GUI even on my wee Pearl.

Cons:

• The application setup presents you with a seemingly endless series of screens, with no indication of when you're going to be done.

Recommended. Free download with ads, or ad-free with a paid annual subscription. BlackBerry only.

The one feature that PDT lacks is integration with PHPUnit. This can be a real hindrance for teams using Test Driven Development, and discourages everyone from frequently running their unit test suite while developing.

Luckily, the Eclipse platform has a mechanism for adding external tools to a project, and makes it very easy to call these tools once they are configured. In this post, I'll outline the steps I took to add PHPUnit support to my installation of PDT.

This post assumes that you have already installed Eclipse, and have a local development environment for PHP and PHPUnit. Jonathan Tran has a handy tutorial on installing PHPUnit on a Windows machine that I found very helpful.

In my PHP projects, I keep my unit tests in a directory called /tests. To start, select any unit test file - I chose AllTests.php, which executes a test suite containing all my unit tests for the project. Once the file is selected, select the menu item Run->External Tools->External Tools Configurations... That brings up a dialog box similar to this.

Select the Program configuration category, and click on the first icon - New Launch Configuration. Name your new configuration PHPUnit.

The location field should contain the full path to your phpunit shell script. On windows, this will be called phpunit.bat. On my computer, the correct location is c:\pear\phpunit.bat; however, this will vary by system.

The Working Directory should be set to the base location of your unit test files. In my case, this is the fully qualified \tests path.

For the Arguments list, you should have one entry - ${resource_name}. This tells Eclipse to pass the name of the currently highlighted unit test to phpunit.bat. To add this, click on the Variables... button and find resource_name in the displayed list.

The remainder of the tabs can be left with their default values. Your finished configuration should look like this:

Press Apply to save your changes. You can now press the Run button to execute PHPUnit immediately, or press Close to exit this dialog box.

After the first time you run PHPUnit using the External Tools Configurations dialog box, your PHPUnit configuration will be associated with the Run External Tools icon on you Eclipse workspace - this is the green Play Button icon decorated with a little red toolbox. To execute any unit test script as you develop, simply select the script in the PHP Explorer and press the Run External Tools icon.

The first step to create a Wordpress plug-in is to create a directory for it to live. Although you can write a plug-in as a single PHP file and just drop it into your plug-in directory, this is not recommended. Ideally, each plug-in will live in it's own directory, and will use sub-directories to organize whatever additional files are needed for the plug-in to work.

For our plug-in, we'll create a directory structure that looks like this:

/wp-content
    /plugins
       /lastfm-album-chart

Within the lastfm-album-chart directory, create a subdirectory called PHP. Into this directory, copy the Album.php and AlbumChart.php files that we created in the last post. The next step is to write a plug-in that uses these two PHP classes to construct our last.fm Album Chart.

The code for the first draft of our plug-in is here:

<?php
/*
Plugin Name: last.fm Album Chart
Plugin URI: http://www.keithlawless.com/
Description: Displays a last.fm user's Weekly Album Chart as a sidebar item.
Version: 0.1
Author: Keith Lawless
Author URI: http://www.keithlawless.com/
*/
include 'php/AlbumChart.php';

/* Create a Wordpress template tag to allow Album Chart to appear on blog
  wherever the lastfm_album_chart() template is called.
*/
function lastfm_album_chart( $username, $apikey, $maxentries ) {
    print "<h2>last.fm Recent Albums</h2>";

    $chart = new AlbumChart( $username, $apikey, $maxentries );
    print $chart->render();
}
?>

The first thing to note in this script are the comments at the top. This comment block is used to identify this code as a Wordpress plug-in. Even without any implementing code, you can create a PHP script that will be recognized by Wordpress and that will show up in the administration panel. Here is ours:

The remainder of the plug-in script is a single function called lastfm_album_chart() that closely follows the logic of the PHP application we wrote in the last post. To use this plugin, the Wordpress site owner simply activates the plug-in, then inserts a call to lastfm_album_chart() wherever in the theme the owner wants the Album Chart to appear - usually in the sidebar.php script. Then, the theme's stylesheet is updated as needed to make the Album Chart blend in with the rest of the site.

The final step before we are finished is to create an options panel for our plug-in. In the current implementation, the site owner has to specify their last.fm username, api, and chart size in the call to the lastfm_album_chart() method. This means that if any of these values change, the owner has to update a php script and FTP the new script to the Wordpress web server. Not a very user-friendly solution.

Creating a Wordpress options panel isn't very difficult; however, you do have to pay attention to detail to make sure your option panel is recognized by the Wordpress administration console. Here is the script above, modified to use an options panel:

<?php
/*
Plugin Name: last.fm Album Chart
Plugin URI: http://www.keithlawless.com/
Description: Displays a last.fm user's Weekly Album Chart as a sidebar item.
Version: 1.0
Author: Keith Lawless
Author URI: http://www.keithlawless.com/
*/
include 'php/AlbumChart.php';

/* Create a Wordpress template tag to allow Album Chart to appear on blog

  wherever the lastfm_album_chart() template is called.
*/
function lastfm_album_chart() {
    print "<h2>last.fm Recent Albums</h2>";

    $username = get_option( "lastfm_albumchart_username" );
    $apikey = get_option( "lastfm_albumchart_apikey" );
    $maxentries = get_option( "lastfm_albumchart_maxentries" );

    $chart = new AlbumChart( $username, $apikey, $maxentries );
    print $chart->render();
}

function lastfm_albumchart_plugin_menu() {
    add_options_page( 'last.fm Album Chart Options',
        'last.fm Album Chart',
        8,
        __FILE__,
        'lastfm_albumchart_plugin_page' );
}

function lastfm_albumchart_plugin_page() {
    // This is the standard class for Wordpress option pages
    echo '<div class="wrap">';

    echo '<h2>last.fm Album Chart</h2>';

    echo '<form method="post" action="options.php">';

    // Add some hidden fields needed for proper page flow.
    echo wp_nonce_field('update-options');

    // Create a form to gather input values for our option fields. This
    // format will give you the "standard" Wordpress look.
    echo '<table class="form-table">';
    echo '<tr valign="top">';
    echo '<th scope="row">last.fm username</th>';
    echo '<td><input type="text" name="lastfm_albumchart_username" value="';
    echo get_option('lastfm_albumchart_username');
    echo '"/></td></tr>';
    echo '<tr valign="top">';
    echo '<th scope="row">last.fm API key</th>';
    echo '<td><input type="text" name="lastfm_albumchart_apikey" value="';
    echo get_option('lastfm_albumchart_apikey');
    echo '"/></td></tr>';
    echo '<tr valign="top">';
    echo '<th scope="row">Number of entries</th>';
    echo '<td><input type="text" name="lastfm_albumchart_maxentries" value="';
    echo get_option('lastfm_albumchart_maxentries');
    echo '"/></td></tr>';
    echo '</table>';

    // Hidden field to pass a command to options.php
    echo '<input type="hidden" name="action" value="update"/>';

    // Enumerate the option fields on this page in a hidden field. Needed
    // by options.php for processing.
    echo '<input type="hidden" name="page_options" value="';
    echo 'lastfm_albumchart_username,';
    echo 'lastfm_albumchart_apikey,';
    echo 'lastfm_albumchart_maxentries';
    echo '"/>';

    // Add a submit button.
    echo '<p class="submit">';
    echo '<input type="submit" name="Submit" value="';
    echo _e( 'Save Changes?' );
    echo '"/>';
    echo '</p>';

    echo '</form>';
    echo '</div>';
}

add_action( 'admin_menu', 'lastfm_albumchart_plugin_menu' );

?>

The first change to note is that our lastfm_album_chart() method no longer requires any parameters. Instead, the three values are obtained by calling the standard Wordpress method get_options(). Note that we chose some long and descriptive names for our three options (eg. lastfm_albumchart_username). This is to make sure our option names do not conflict with any other plug-ins, or with the core set of Wordpress options.

To create and activate the options page, we add two functions. lastfm_albumchart_plugin_menu() is called whenever the options main menu is created. The line line of this script contains a call to add_action() that registers this method with the Administration menu. Within the lastfm_albumchart_plugin_menu function, we make a call to the Wordpress function add_options_page(). This is the trickiest part of the process - it creates a new option page called 'last.fm Album Chart Options', which is invoked by a menu item called 'last.fm Album Chart'. The value 8 specifies that only site editors can access this menu item. This is part of Wordpress' security system for multi-user sites. The __FILE__ parameter specifies that the method for creating the options page is in this PHP script. The final parameter is the name of the method to use to create the option page.

The lastfm_albumchart_plugin_page() method uses the PHP echo command to output the HTML needed to build the options page. Note that this isn't a complete HTML page with <head> and <body> tags - this is just the markup needed to display our option form within the larger Wordpress administration console.

When creating your own options pages, you should copy another page to make sure you are following the Wordpress guidelines for option pages. An option page contains both CSS styles to make sure the option page is displayed correctly, as well as hidden fields used to inform the Administration console what options you are updating, and what values to change.

The administration panel that is created after our revised plug-in script is uploaded and activated looks like this:

This is a very basic options page that just shows the three field names and their current values. By making the lastfm_albumchart_plugin_page() method more elaborate we could add additional refinements like detailed instructions for each field, or friendlier form elements like a drop down list.

That's the final step in creating our last.fm plugin. Once the sidebar.php script is updated to call the plug-in, and some CSS styling is applied, the final product looks like this.

I hope you found this series helpful. Please feel free to leave a comment or contact me via Facebook.

Before getting started, we should decide what we want to the widget to look like, and what information it should display. Since we'll be pulling in the weekly Album Chart, it makes sense for our widget to display the top five albums that the user has listened to over the past week - that is, the first five entries in the Album Chart. Once we have the list, we'll pull in additional information about each album. This will allow us to display a little thumbnail image of the album's CD cover if one is available.

The finished widget should look something like this:

At the end of the last post we took a look at the API method to retrieve information about a specific album. Using an object-oriented design, we can create a PHP script that encapsulates information about an album. The script is shown here:

<?php
class Album {

    private $artist = "";
    private $name = "";
    private $apikey = "";
    private $albumurl = "";
    private $imageurl = "";

    public function __construct( $p_artist, $p_name, $p_apikey ) {
        $this->artist = $p_artist;
        $this->name = $p_name;
        $this->apikey = $p_apikey;

        $this->fetchAlbum();
    }

    public function render() {
        $ret = "<li>";

        if( $this->imageurl != "" ) $ret = $ret .
            "<a href=\"" . $this->albumurl . "\">" .
            "<img width=\"34\" height=\"34\" src=\"" .
            $this->imageurl . "\"></a> ";

        $ret = $ret . "<a href=\"" .
            $this->albumurl . "\">" .
            $this->artist . " - " . $this->name . "</a>";

        return $ret;
    }

    private function fetchAlbum() {
        $url = "http://ws.audioscrobbler.com/2.0/?method=album.getinfo" .
            "&artist=" . urlencode($this->artist) .
            "&album=" . urlencode($this->name) .
            "&api_key=" . $this->apikey;
        $input = file_get_contents($url)
            or die('Could not access file: ' . $url );
        $xmlobj = simplexml_load_string($input);

        $return_code_array = $xmlobj->xpath("@status");
        $return_code = $return_code_array[0];

        if( $return_code != "ok" )
            die('Last.fm returned an error: ' . $xmlobj->error );

        $this->albumurl = $xmlobj->album->url;
        $imageurl_array = $xmlobj->xpath("//image[@size='small']");
        $this->imageurl = $imageurl_array[0];
    }
}
?>

The class Album performs two functions - it fetches the album information using the last.fm API, and it provides a render() method that creates and returns a <li> element for the album. The user of this class only has to provide the artist and album name, along with a valid last.fm API key. The mechanics of fetching and rendering the album information is hidden within the class.

In the fetchAlbum() method, we added some error checking to make sure we found a match for our album. Since last.fm is providing the list of albums to us, we should never encounter an "Album not found" error - however, having the error checking gives you a nice piece of reusable code you can use in other applications. Also in fetchAlbum() we use this statement to fetch the album image URL:

$imageurl_array = $xmlobj->xpath("//image[@size='small']");

Xpath is a standard way of querying XML documents, and is supported in many different programming languages. This query says to find all of the <image> elements that have an attribute of "size" with a value of "small." That is, an element that looks like this:

<image size="small">

Now that we have the code to build an individual album's list item, we need to build the overall Album Chart. We developed some rudimentary code in the last post to accomplish this. Here is a more refined version of that code, implemented an AlbumChart class:

include_once 'Album.php';

class AlbumChart {
    private $user = "keithlawless";
    private $apikey = "14d5668dc30efbc02489d78dfc32da26";
    private $max = 5;

    private $albums;

    public function __construct( $p_user="", $p_apikey="", $p_max=5 ) {
        if( $p_user != "" ) {
            $this->user = $p_user;
        }

        if( $p_apikey != "" ) {
            $this->apikey = $p_apikey;
        }

        if( $p_max != "" ) {
            $this->max = $p_max;
        }

        $this->fetchChart();
    }

    public function render() {
        $ret = "<ul>";

        foreach( $this->albums as $album ) {
            $ret = $ret . $album->render();
        }

        $ret = $ret . "</ul>";
        return $ret;
    }

    private function fetchChart() {
        $url = "http://ws.audioscrobbler.com/2.0/?method=user.getweeklyalbumchart" .
            "&user=" . $this->user .
            "&api_key=" . $this->apikey;

        $input = file_get_contents($url) or die('Could not access file:' . $url);
        $xmlobj = simplexml_load_string($input);

        $return_code_array = $xmlobj->xpath("@status");
        $return_code = $return_code_array[0];

        if( $return_code != "ok" )
            die('Last.fm returned an error: ' . $xmlobj->error );

        $count = 0;
        foreach( $xmlobj->weeklyalbumchart->album as $album ) {
            $artist = $album->artist;
            $name = $album->name;

            $album = new Album( $artist, $name, $this->apikey );
            $this->albums[$count] = $album;

            // If we've hit the maximum number of albums requested,
            // break the loop.
            $count++;
            if( $count == $this->max ) break;
        }
    }
}
?>

After getting the AlbumChart from last.fm, we iterate through the array of album elements are returned. For each album, we parse out the artist and title, and create a new Album object, which we store in an array. Once we reach the maximum number of albums we want to display - or run out of albums - we stop the loop. To display the Album chart, we simply create an unordered list, an iterate over the array of Album objects, calling each object's render method.

All that's left now is to create the widget script itself. Here is the code:

<html>
    <head>
        <title>last.fm Widget Test</title>
    <body>
        <h2>last.fm Recent Albums</h2>
        <?php
            include 'AlbumChart.php';
            $chart = new AlbumChart();
            print $chart->render();
        ?>
    </body>
</html>

We simply create an AlbumChart object, and call it's render() method to display the widget. To customize this widget for your site, you can select a different last.fm username and API key by passing parameters when creating the AlbumChart object - for example:

$chart = new AlbumChart( "YourUserName", "Your API Key" );

This code can be used "as is" in your Wordpress blog - you simply drop the code above into your sidebar.php script for your current template, and make any needed adjustments. In the next post, we'll go one step further, and create a Wordpress plug-in that makes it even easier to use this code for your blog.

This post is the first in a series of three exploring this API, and showing how the API can used to create a Wordpress plug-in for displaying information from your last.fm profile on your blog. In this first post, we'll take a look at the last.fm API, and create some simple PHP scripts to test out the API. In the second post, we'll turn our simple scripts into a complete PHP application. In the third post, we'll create a Wordpress plug-in that leverages our PHP application to display our last.fm data on a blog.

The last.fm API is accessed in two ways. For querying data, a simple HTTP GET is used, passing any variables as part of the request URL. This method does not require authentication, and returns data as an XML document in response to GET. All of the examples in this series of posts use this method. For API methods that modify a user's data, HTTP POSTs are used along with an authentication callback to the originating web site. Each type method requires a freely available API key. The examples here use my API key - I recommend that you sign up for your own, although all of the examples here will work with any recognized API key.

For our Wordpress plug-in, we are going to display the last.fm user's Album Chart. This is a personalized Weekly Top Album list for each user, showing the albums that received the greatest number of plays during the previous week. The URL to call to get the Album Chart looks like this:

http://ws.audioscrobbler.com/2.0/?method=user.getweeklyalbumchart&
user=keithlawless&api_key=14d5668dc30efbc02489d78dfc32da26

This URL is very similar to the rest of the query API's: a method name is passed which takes the form object.action, followed by a user name (if needed) and the caller's API key. The call returns an XML document. You should be able to be paste the URL above into your browser and see the most recent Album Chart for my last.fm account.

    
        
            The Tangent
            Not As Good As The Book
            
10
            http://www.last.fm/music/The+Tangent/Not+As+Good+As+The+Book
        
        
            Porcupine Tree
            The Sky Moves Sideways
            61b42968-ed19-45cd-a56e-43f5f3fa0d71
7
            http://www.last.fm/music/Porcupine+Tree/The+Sky+Moves+Sideways
        
        
            Porcupine Tree
            Fear of a Blank Planet
            
6
            http://www.last.fm/music/Porcupine+Tree/Fear+of+a+Blank+Planet
        
        
            Robert Fripp
            Radiophonics Soundscapes vol.1: Live in Argentina
            
6
            http://www.last.fm/music/Robert+Fripp/Radiophonics+Soundscapes+vol.1%3A+Live+in+Argentina
        
        
            Carole King
            Carole King - Her Greatest Hits: Songs Of Long Ago
            
2
            http://www.last.fm/music/Carole+King/Carole+King+-+Her+Greatest+Hits%3A+Songs+Of+Long+Ago
        
    

Each returned XML document will contain a status attribute in the lfm element. If the call was successful, there will be one child element containing the result - in this case a weeklyalbumchart element. This element contains a series of album elements - one for each album on our Chart.

Accessing the last.fm API from a PHP script is easy because of two nice features of PHP. First, PHP will accept a URL in most places where a local file name is called for. This allows you to quickly get the result of an HTTP call as if the result was a file on your hard drive. Second, PHP contains a simple XML parsing library called SimpleXML that allows XML documents to be treated like native PHP objects. The following PHP script calls the same URL as above, and creates an HTML list of albums from the Album Chart.

 <html>
 <body>
    <?php
        $apikey = "14d5668dc30efbc02489d78dfc32da26";
        $user = "keithlawless";
        $url = "http://ws.audioscrobbler.com/2.0/?method=user.getweeklyalbumchart&user=" .
            $user . "&api_key=" . $apikey;

        $input = file_get_contents($url)
            or die('Could not access file: $url');

        $xmlobj = simplexml_load_string($input); 

        $return_code_array = $xmlobj->xpath("@status");

        print "<h2>Status code was: " . $return_code_array[0] . "</h2>";

        print "<ul>";
        foreach( $xmlobj->weeklyalbumchart->album as $album ) {
            print "<li><a href=\"" . $album->url . "\">" .
                $album->artist . " - " . $album->name . "</a>";
        }
        print "</ul>";
    ?>
</body>
</html>

In line 6 of this example, we assemble the URL to pass to last.fm. In line 9, we use the php function file_get_contents to call the URL and return the resulting XML document as a string. A call is made to simplexml_load_string() on line 12 - this converts the XML document to a PHP object. The simplexml class allows xpath expressions - this is demonstrated on line 14, where we use the xpath expression "@status" to return all status attributes in the XML document as an array. On line 16 we displayed the first (and only) occurrence of status. Lines 19-22 is a loop over all of the album elements that are children of the weeklyalbumchart element. Each of the album elements is a SimpleXML object as well - allowing the url, artist, and name elements to be accessed using the normal "arrow" notation.

The resulting page is shown here:

For the plug-in, it would be nice to display more information about each album in the Album Chart. To do that, we'll use the album.getInfo API method. A sample URL for this method is:

http://ws.audioscrobbler.com/2.0/?method=album.getinfo&
artist=Porcupine%20Tree&album=The%20Sky%20Moves%20Sideways&
api_key=14d5668dc30efbc02489d78dfc32da26

Note that this URL does not require a username field in the request since the album information isn't specific to a user. However, a valid API key is required. The resulting XML document looks something like this (some elements are removed to save space).

    The Sky Moves Sideways
    Porcupine Tree
    1429130
    61b42968-ed19-45cd-a56e-43f5f3fa0d71
    http://www.last.fm/music/Porcupine+Tree/The+Sky+Moves+Sideways
        5 Sep 1995, 00:00
    http://userserve-ak.last.fm/serve/34s/12007055.jpg
    http://userserve-ak.last.fm/serve/64s/12007055.jpg
    http://userserve-ak.last.fm/serve/174s/12007055.jpg
    http://userserve-ak.last.fm/serve/300x300/12007055.jpg
26561
250718

Of particular interest in this XML are the image tags. In the next post when we create a complete PHP application, we'll use this information to put a little image next to each entry on our chart. At this point, you should note that not all of the album elements will be present for every album. last.fm will record each album and track that you listen to based on the tagging information contained in the track. However, not all artists are in last.fm's internal databases.

That's it for this post - keep an eye out for Part 2 where we'll put all of this together into a complete PHP application.

Despite being my sixth presidential election, I don't remember ever being this excited to vote. I was shaking with excitement - hopefully the machine can read my slightly wobbly arrows.