Usage

From phplastfmapi

This guide will take you through the basics of using the PHP Last.fm API classes. Follow the instructions and you'll soon be on your way to making use of this great API.

Contents 1 Step 1: Download 2 Step 2: Install 3 Step 3: Include library 4 Step 4: Create auth class 4.1 Unauthenticated methods 4.2 Authenticated methods 4.2.1 Get new information (once only) 4.2.2 Set information (everytime after the first) 5 Step 5: Create package class 6 Step 6: Call method

Step 1: Download

The first thing to do is to download the latest version of the library. Take a look at the downloads page for the latest release or at the SVN page for the bleeding-edge development release.

Step 2: Install

It is very simple to install the files in your application. Simply extract the entire lastfmapi folder into a place on your webserver. This can be ahywhere as long as you know the path to it.

Step 3: Include library

To include the library and make all of the classes avalialbe to your PHP script you need to include the lastfmapi.php file. Use this code to include it:

require 'PATH_TO_LIBRARY/lastfmapi.php';

Step 4: Create auth class

To make any call using the library you need to create an instance of the auth class. You will need this even if the Last.fm documentation say it doesnt require authentication. This is because the auth class alway contains the API key, which is required for all calls to the API.

Unauthenticated methods

For methods that don't require full authentication you need to create an auth class that contains an API key. To do this you would use this PHP code:

$authVars['apiKey'] = 'YOUR_API_KEY_HERE';
$auth = new lastfmApiAuth('setsession', $authVars);

$auth will now contain your auth class which will be passed onto the classes in the next step.

Authenticated methods

Get new information (once only)

For methods that require authenticatication you need to create an auth class with additional information.

This information first needs to be obtained from Last.fm. As a conviniance you can use this peice of conde in your script when you wish to request new information from Last.fm:

$authVars['apiKey'] = 'YOUR_API_KEY_HERE';
$auth = new lastfmApiAuth('getsession', $authVars);

When this code is called you will be sent to a page on the Last.fm website where the user will grant your application full authentication. When the user has granted this perission they will be sent to the callback URL you set (To set your callback URL look here).

When on the callback page you will have access to the extra peices of information needed for a full authentication in the token GET variable. Armed this this extra variable you can create a fully authenticated class using this code:

$vars = array(
	'apiKey' => 'YOUR_API_KEY_HERE',
	'secret' => 'YOU_SECRET_HERE',
	'token' => 'TOKEN_HERE'
);
$auth = new lastfmApiAuth('getsession', $vars);

$auth will now contain all the information for a fully authenticated method call.

As you are only meant use the getsession code once for each user you will need to store the information in the auth class somewhere. You could use either a flat file system of a database system depending on your needs. You can access the information from the class using thise variable names:

$auth->apiKey
$auth->secret
$auth->username
$auth->sessionKey
$auth->subscriber

Set information (everytime after the first)

The next time you want to create an auth class with full authenticated you would use code like this:

$vars = array(
	'apiKey' => 'YOUR_API_KEY_HERE',
	'secret' => 'YOUR_SECRET_HERE',
	'username' => 'USERNAME_FROM_GETSESSION',
	'sessionKey' => 'SESSION_KEY_FROM_GETSESSION',
	'subscriber' => 'SUBSCRIBER_FROM_GETSESSION'
);
$auth = new lastfmApiAuth('setsession', $vars);

This will give you a fully authenticated auth class for use with methods.

Step 5: Create package class

A package a collection of API methods. For example the playlist package has the methods:

• playlist.addTrack
• playlist.fetch

To use any method you need to create a class for it's package using this simple bit of code:

$apiClass = new lastfmApi();
$packageClass = $apiClass->getPackage($auth, 'PACKAGE_NAME');

$packageClass will now allow you to access the methods of that package.

Step 6: Call method

Calling a method is now very simple. For example to call the user.getTopTracks method you would use code like this:

$methodVars = array(
	'user' => $username
);
if ( $artists = $packageClass->getTopArtists($methodVars) ) {
	// Method call is a success. Process the array returned here
}
else {
	// Error: show which error and go no further.
	echo '<b>Error '.$packageClass->error['code'].' - </b><i>'.$packageClass->error['desc'].'</i>';
}

For information how to use each methods in more detail see the Method Reference.