README

🚀 MINIMAL YET POWERFUL! Focused, lightweight Last.fm API client — as compact as possible while maintaining modern PHP comfort and clean APIs.

📦 Installation

composer require calliostro/lastfm-client

Do You Need to Register?

For ALL API calls: Registration required

Register your application at Last.fm to get credentials
API Key needed for: ALL methods (artist info, search, charts, etc.)

For write operations: Session authentication required

Session Key needed for: scrobbling, loving tracks, personal collections, tagging

🚀 Quick Start

Read-only data (API key required for all methods):

$lastfm = LastFmClientFactory::createWithApiKey('your-api-key', 'your-secret');

$artist = $lastfm->getArtistInfo('Billie Eilish');          // Get artist info
$release = $lastfm->getAlbumInfo('The Weeknd', 'Dawn FM');  // Album info  
$charts = $lastfm->getTopArtistsChart();                    // Global charts

Search with API credentials:

$lastfm = LastFmClientFactory::createWithApiKey('your-api-key', 'your-secret');

// Positional parameters (traditional)
$results = $lastfm->searchArtists('Taylor Swift', 20);
$tracks = $lastfm->searchTracks('Anti-Hero', 'Taylor Swift');

// Named parameters (PHP 8.0+, recommended for clarity)
$results = $lastfm->searchArtists(artist: 'Taylor Swift', limit: 20);
$tracks = $lastfm->searchTracks(track: 'Anti-Hero', artist: 'Taylor Swift');

Your scrobbles (session authentication):

$lastfm = LastFmClientFactory::createWithSession('your-api-key', 'your-secret', 'your-session-key');

$collection = $lastfm->getUserRecentTracks('your-username');
$loved = $lastfm->getUserLovedTracks('your-username');

// Scrobble and love tracks with named parameters
$lastfm->scrobbleTrack(
    artist: 'Bad Bunny',
    track: 'Un Verano Sin Ti',
    timestamp: time()
);

Multi-user apps (mobile auth):

$lastfm = LastFmClientFactory::createWithMobileAuth('your-api-key', 'your-secret', 'your-username', 'your-password');

$identity = $lastfm->getUserInfo();

✨ Key Features

Simple Setup – Works immediately with an API key, easy authentication for advanced features
Complete API Coverage – All 55+ Last.fm API endpoints supported
Clean Parameter API – Natural method calls: getArtistInfo('Billie Eilish') with named parameter support
Lightweight Focus – Minimal codebase with only essential dependencies
Modern PHP Comfort – Full IDE support, type safety, PHPStan Level 8 without bloat
Secure Authentication – Full session and mobile authentication support
Well Tested – 100% test coverage, PSR-12 compliant
Future-Ready – PHP 8.1–8.5 compatible (beta/dev testing)
Pure Guzzle – Modern HTTP client, no custom transport layers

🎵 All Last.fm API Methods as Direct Calls

Album Methods – getAlbumInfo(), searchAlbums(), getAlbumTopTags(), addAlbumTags(), removeAlbumTag(), getAlbumTags()
Artist Methods – getArtistInfo(), getArtistTopTracks(), getSimilarArtists(), searchArtists(), getArtistTopAlbums(), getArtistCorrection(), addArtistTags(), removeArtistTag(), getArtistTags(), getArtistTopTags()
Track Methods – getTrackInfo(), searchTracks(), getSimilarTracks(), scrobbleTrack(), updateNowPlaying(), loveTrack(), unloveTrack(), getTrackCorrection(), addTrackTags(), removeTrackTag(), getTrackTags(), getTrackTopTags()
User Methods – getUserInfo(), getUserRecentTracks(), getUserLovedTracks(), getUserTopArtists(), getUserTopTracks(), getUserTopAlbums(), getUserFriends(), getUserArtistTracks(), getUserPersonalTags(), getUserTopTags()
Chart Methods – getTopArtistsChart(), getTopTracksChart(), getTopTagsChart()
Geography Methods – getTopArtistsByCountry(), getTopTracksByCountry()
Tag Methods – getTagInfo(), getSimilarTags(), getTagTopArtists(), getTagTopTracks(), getTagTopAlbums(), getTopTags(), getTagWeeklyChartList()
Authentication Methods – getToken(), getSession(), getMobileSession()
Library Methods – getLibraryArtists()
User Charts – getUserWeeklyArtistChart(), getUserWeeklyAlbumChart(), getUserWeeklyTrackChart(), getUserWeeklyChartList()

All Last.fm API endpoints are supported with clean documentation — see Last.fm API Documentation for complete method reference

💡 Note: Some endpoints require authentication (scrobbling, user libraries) or specific permissions.

📋 Requirements

php ^8.1
guzzlehttp/guzzle ^6.5 || ^7.0

⚙️ Configuration

Configuration

Simple (works out of the box):

use Calliostro\LastFm\LastFmClientFactory;

$lastfm = LastFmClientFactory::createWithApiKey('your-api-key', 'your-secret');

Advanced (middleware, custom options, etc.):

use Calliostro\LastFm\LastFmClientFactory;
use GuzzleHttp\{HandlerStack, Middleware};

$handler = HandlerStack::create();
$handler->push(Middleware::retry(
    fn ($retries, $request, $response) => $retries < 3 && $response?->getStatusCode() === 429,
    fn ($retries) => 1000 * 2 ** ($retries + 1) // Rate limit handling
));

$lastfm = LastFmClientFactory::createWithApiKey('your-api-key', 'your-secret', [
    'timeout' => 30,
    'handler' => $handler,
    'headers' => [
        'User-Agent' => 'MyApp/1.0 (+https://myapp.com)',
    ]
]);

💡 Note: By default, the client uses LastFmClient/2.0.0 +https://github.com/calliostro/lastfm-client as User-Agent. You can override this by setting custom headers as shown above.

🔐 Authentication

Get credentials at Last.fm API Registration.

Quick Reference

What you want to do	Method	What you need
Get artist/track/chart info	`createWithApiKey()`	API key + secret
Search the database	`createWithApiKey()`	API key + secret
Scrobble tracks	`createWithSession()`	API key + secret + session
Access user collections	`createWithSession()`	API key + secret + session
Mobile app	`createWithMobileAuth()`	API key + secret + user/pass

Complete Session Flow Example

Step 1: authorize.php – Redirect user to Last.fm

<?php
// authorize.php

use Calliostro\LastFm\AuthHelper;

$apiKey = 'your-api-key';
$secret = 'your-secret';
$callbackUrl = 'https://yourapp.com/callback.php';

$auth = new AuthHelper($apiKey, $secret);

// For web apps, you can skip token generation and redirect directly:
$authUrl = "https://www.last.fm/api/auth/?api_key={$apiKey}&cb=" . urlencode($callbackUrl);

// For desktop apps, generate token first:
// $tokenData = $auth->getToken();
// $authUrl = $auth->getAuthorizationUrl($tokenData['token']);

header("Location: {$authUrl}");
exit;

Step 2: callback.php – Handle Last.fm callback

<?php
// callback.php

require __DIR__ . '/vendor/autoload.php';

use Calliostro\LastFm\{AuthHelper, LastFmClientFactory};

$apiKey = 'your-api-key';
$secret = 'your-secret';
$token = $_GET['token'];

$auth = new AuthHelper($apiKey, $secret);
$sessionData = $auth->getSession($token);

$sessionKey = $sessionData['session']['key'];
$username = $sessionData['session']['name'];

// Store tokens for future use
$_SESSION['lastfm_session_key'] = $sessionKey;
$_SESSION['lastfm_username'] = $username;

$lastfm = LastFmClientFactory::createWithSession($apiKey, $secret, $sessionKey);
$user = $lastfm->getUserInfo();
echo "Hello " . $user['user']['name'];

🤝 Contributing

Contributions are welcome! See DEVELOPMENT.md for detailed setup instructions, testing guide, and development workflow.

📄 License

MIT License – see LICENSE file.

🙏 Acknowledgments

Last.fm for providing the excellent music data and scrobbling API
Guzzle for the robust HTTP client
The PHP community for continuous inspiration

⭐ Star this repo if you find it useful!

calliostro / lastfm-client

Maintainers

Details