Added by Chris Hartjes, last edited by Bill Karwin on Nov 15, 2006 (view change)

Labels

Zend Framework: Zend_Service_Audioscrobbler Component Proposal

Proposed Component Name	Zend_Service_Audioscrobbler
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Service_Audioscrobbler
Proposers	Chris Hartjes Derek Martin
Revision	1.0 - 1 July 2006 (wiki revision: 20)

1. Overview
2. References
3. Component Requirements, Constraints, and Acceptance Criteria
4. Dependencies on Other Framework Components
5. Theory of Operation
6. Milestones / Tasks
7. Class Index
8. Use Cases
9. Class Skeletons

1. Overview

Zend_Service_Audioscrobbler provides a simple API to access Audioscrobbler's web services

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

A simple API for accessing Audioscrobbler's web services

4. Dependencies on Other Framework Components

Zend_Service_Rest
Zend_Service_Exception

5. Theory of Operation

Results from Audioscrobbler's REST services are returned as SimpleXML objects, otherwise a Zend_Service_Exception is thrown containing an informative error message.

6. Milestones / Tasks

alpha 0.01 released November 15th, 2006

7. Class Index

Zend_Service_Audioscrobbler

8. Use Cases

UC-01

$as = new Zend_Service_Audioscrobbler();
$as->set('user', 'BigDaddy71);
$profile_info = $as->userGetProfileInformation();

print "Pulling information on {$profile_info->realname}<br />";
print "User info can be found at {$profile_info->url}<br />";

UC-02

$as = new Zend_Service_Audioscrobbler();
$as->set('artist', 'LCD Soundsystem');
$related_artists = $as->artistGetRelatedArtists();

foreach ($related_artists as $artist) 
{
    print "<a href={$artist->url}>{$artist->name}</a><br />";
}

UC-03

$as = new Zend_Service_Audioscrobbler();
$as->set('user', 'lo_fye');
$from = '1114965332';
$to = '1115570132';
$previous_weekly_artists = $as->userGetWeeklyArtistChart($from, $to);

foreach ($previous_weekly_artists as $artist) 
{
    print "<a href={$artist->url}>{$artist->name}</a><br />";
}

9. Class Skeletons

Zend_Service_Audioscrobbler __construct ()
void albumGetInfo ()
SimpleXML artistGetRelatedArtists ()
SimpleXML artistGetTopAlbums ()
SimpleXML artistGetTopFans ()
SimpleXML artistGetTopTags ()
SimpleXML artistGetTopTracks ()
void get ( $field, string $key)
void group ()
void groupGetWeeklyArtistChartList ()
void groupGetWeeklyChartList ()
void set (string $field, $value, string $val)
void tagGetTopArtists ()
void tagGetTopTags ()
void tagGetTopTracks ()
void trackGetTopFans ()
void trackGetTopTags ()
SimpleXML userGetFriends ()
SimpleXML userGetNeighbours ()
array userGetProfileInformation ()
SimpleXML userGetRecentBannedTracks ()
SimpleXML userGetRecentLovedTracks ()
SimpleXML userGetRecentTracks ()
SimpleXML userGetTopAlbums ()
array userGetTopArtists ()
SimpleXML userGetTopTags ()
SimpleXML userGetTopTagsForAlbum ()
SimpleXML userGetTopTagsForArtist ()
SimpleXML userGetTopTagsForTrack ()
SimpleXML userGetTopTracks ()
SimpleXML userGetWeeklyAlbumChart ($from, $to)
SimpleXML userGetWeeklyArtistChart ($from, $to)
SimpleXML userGetWeeklyChartList ()
SimpleXML userGetWeeklyTrackChart ($from, $to)

Comments (Hide Comments)

I'll confess that I don't know what Audioscrobbler is, but surely there is a better way to implement an interface to it than a class with almost 60 methods. Isn't it possible to split it up somehow?

Posted by Matthew Ratzloff at Jul 11, 2006 17:04

Hi Matthew.

Audioscrobbler is a site that tracks what you listen to via their iTunes/Winamp/etc plug-in installed, or via streaming audio at http://www.last.fm

Our goal was to simply provide a php interface to Audioscrobbler's existing web service. There is a 1:1 correlation between our methods and their service URLs, right down to the method naming.

We would have loved not to have 60 methods, but then our API wouldn't correlate to theirs. Plus, that would have meant more thinking for us

ttys,

Derek

Posted by Derek Martin at Jul 29, 2006 21:52

Perhaps you could use __call to transparently pass methods to the Audioscrobbler object and then throw an error only if the Audioscrobbler method is non-existent? It would mean a much leaner component and probably a lot less work to maintain it whenever the service is upgraded.

Posted by Simon Mundy at Aug 28, 2006 19:31

I haven't used __call much so I'll take a look at that. If it makes for a better component, I'm definitely in favour of it.

Posted by Chris Hartjes at Sep 28, 2006 15:46

Yeah, I've been doing a bunch of work on this lately and have simplified a lot of the function calls to minimize duplication. Check out the latest in SVN in the incubator

Posted by Chris Hartjes at Sep 28, 2006 15:45

I use Last.fm and I love it, but I must ask, is the framework a good place to have this? I see uses for the Amazon, Flickr and Yahoo! service implementations, but how would this one be beneficial to the framework apart from providing some interaction with the framework?

Posted by Elisamuel Resto at Jul 30, 2006 00:14

Subject: RE: [fw-general] MIA – orm & acl?
Date: Tue, 11 Jul 2006 16:08:23 -0700
From: Andi Gutmans <andi@zend.com>

Well I don't know about AudioScrobbler specifically as I haven't reviewed it
yet, but all Zend_Service_* contributions are very important IMO. We are
planning to review them very soon and we'd definitely like the amount of
out-of-the-box sevices in Zend Framework grow rapidly. We think although it
might not be difficult to consume many of these services with standard PHP,
having concrete implementations in the Zend Framework will make them even
easier to use.

It'd be extremely cool if this would become the best place to use any of the
popular Web Services on the Internet.

Posted by Gavin at Aug 28, 2006 18:59

Zend Comments

The proposal is approved on the condition that the following issues are addressed by the proposal author.

Public properties make the set* methods redundant. Ideas for resolution:

Change the properties to be protected and using the existing set* methods along with new corresponding get* methods.
Override __get() and __set(), storing properties in a protected array.

Another option would be to pass the "properties" as method arguments:

<?php
$as = new Zend_Service_Audioscrobbler();
$profileInfo = $as->userGetProfileInformation('BigDaddy71');
$relatedArtists = $as->artistGetRelatedArtists('LCD Soundsystem');
// ...
?>

No underscores within variable names and compliance with other coding standards.

What is the reason that setDate() and getInfo() methods are designated private? Should they not be inherited and accessible by subclasses, and if so, why not?

We should leverage Zend_Date as it becomes available for date-specific operations.

How do Zend_Service_Audioscrobbler and the Audioscrobbler web services support limiting the number of records returned by a request?

The API presented causes extra effort to programmatically select functionality, due to the practice of essentially embedding options into the method names. Usually function names accept parameters to select between different, related behaviors. For example, the proposal shows:

public function userGetRecentWeeklyArtistChart()
public function userGetRecentWeeklyAlbumChart()
public function userGetRecentWeeklyTrackChart()
public function userGetPreviousWeeklyArtistChart()
public function userGetPreviousWeeklyAlbumChart()
public function userGetPreviousWeeklyTrackChart()

Using class constants having string values we could nicely refactor the above list of methods to something like:

getChart($type, $recent = true)

Similarly, what about:

// source = 'user' | 'artist'
// type = 'artists' | 'albums' | 'tracks' | etc.
getTop($source, $type)

Posted by Darby Felton at Aug 29, 2006 14:03

Hi Darby,

I've finally managed to set some time aside to address these issues. Here are my thoughts:

I'll make the variables protected and user get and set methods as appropriate

That really does make sense and is consistent

I'll remove the underscores to make it compliant with coding standards

Zend_Date is a good idea for the time stamp parameters, but Audioscrobbler currently only accepts timestamps so the ability to convert would be ok

I'm not sure if Audioscrobbler limits the result sets it sends out, I will ask them

I've massively simplified the API to reduce the number of functions

That was just silly on our part in the first place

I will investigate how I might make something work like your suggestion on an API with calls like getTop($source, $type, $params = NULL) to make it look really slick.

Thanks again for all the great suggestions.

Posted by Chris Hartjes at Sep 28, 2006 15:54

Thank you for implementing the interface to the Audioscrobbler web service in Zend Framework! Currently, there is an annoying bug in the private getInfo() method, though. The following code example:

$as = new Zend_Service_Audioscrobbler();
$as->set('artist', 'This is an unknown artist.');
$as->set('track', 'Track does not matter.');
$tags = $as->trackGetTopTags();

results in a PHP Fatal error:

PHP Fatal error: Call to a member function getStatus() on a non-object in /var/httpd/servers/noise.graefe.net/lib/ZendFramework-0.9.1-Beta/library/Zend/Service/Audioscrobbler.php on line 165

My suggestion is to change the error handling in getInfo() to something like this:

if ($response == 'No such path') {
    throw new Zend_Http_Client_Exception('Could not find: ' . $this->_client->getUri());
} else if ($request->isError()) {
    if (is_object($response)) {
        throw new Zend_Http_Client_Exception('The web service ' . $this->_client->getUri() . ' returned the following status code: ' . $response->getStatus());
    } else {
        throw new Zend_Http_Client_Exception( $response );
    }
} else {
    return simplexml_load_string($response);
}

I would have opened an issue in the tracker but either I'm to blind to find the button to do so, or I'm not allowed to.

Posted by Christian Gräfe at Mar 30, 2007 05:11

Page Operations

Browse Space

Zend_Service_Audioscrobbler Proposal - Chris Hartjes, Derek Martin