README

📦 Packagist · 📚 Docs · 📜 Changelog · 🔗 Last.fm API

A modern, type-safe Last.fm API client for Laravel 7-13. Built with fluent interfaces, full type hints, and dependency injection support.

Documentation

Features

API Integration

Fluent interface for all major Last.fm API endpoints
User statistics and track information retrieval
Weekly and overall chart data
Now-playing track detection

Laravel Integration

Auto-registration via package discovery (Laravel 5.5+)
Dependency injection support
Configuration publishing
Service provider binding

Developer Experience

Full type hints and strict mode
Chainable query builder pattern
Per-request period and limit filtering
Tested against Laravel 7, 8, 9, 10, 11, 12, and 13

Requirements

PHP >= 7.4
Laravel >= 7.0
Guzzle HTTP Client 6 or 7

Installation

Install via Composer:

composer require thatobabusi/laravel-lastfm

Configuration

Add your Last.fm API key to your .env file:

LASTFM_API_KEY=your_api_key_here

Or publish and customize the configuration file:

php artisan vendor:publish --provider="Thatobabusi\LaravelLastFm\LastfmServiceProvider"

For Laravel versions prior to 5.5, manually register the service provider in config/app.php:

'providers' => [
    ...
    Thatobabusi\LaravelLastFm\LastfmServiceProvider::class,
];

Usage

Basic Example

Inject the Lastfm class into your controller or service:

use Thatobabusi\LaravelLastFm\Lastfm;

public function topAlbums(Lastfm $lastfm)
{
    $albums = $lastfm->userTopAlbums('username')->get();
    return view('albums', compact('albums'));
}

Available Methods

User Statistics

userTopAlbums(string $username) — Get user's top albums
userTopArtists(string $username) — Get user's top artists
userTopTracks(string $username) — Get user's top tracks
userInfo(string $username) — Get user profile information
userRecentTracks(string $username) — Get user's recent tracks

Real-time Data

nowListening(string $username) — Get currently playing track (or false)

Weekly Charts

userWeeklyTopAlbums(string $username, DateTime $startdate) — Get weekly top albums
userWeeklyTopArtists(string $username, DateTime $startdate) — Get weekly top artists
userWeeklyTopTracks(string $username, DateTime $startdate) — Get weekly top tracks
userWeeklyChartList(string $username) — Get list of available weekly charts

Filtering Results

Chain methods to customize your queries:

use Thatobabusi\LaravelLastFm\Constants;

// Filter by time period
$lastfm->userTopAlbums('username')
    ->period(Constants::PERIOD_MONTH)
    ->get();

// Limit results
$lastfm->userTopAlbums('username')
    ->limit(5)
    ->get();

// Paginate through results
$lastfm->userTopAlbums('username')
    ->limit(10)
    ->page(2)
    ->get();

Time Periods

Use these constants with the ->period() method:

Constants::PERIOD_WEEK       // Last 7 days
Constants::PERIOD_MONTH      // Last month
Constants::PERIOD_3_MONTHS   // Last 3 months
Constants::PERIOD_6_MONTHS   // Last 6 months
Constants::PERIOD_YEAR       // Last 12 months
Constants::PERIOD_OVERALL    // All time

Getting an API Key

Create a Last.fm account and generate an API key at: http://www.last.fm/api/account/create

API Documentation

For complete Last.fm API reference, see: http://www.last.fm/api

Testing

Copy phpunit.xml.dist to phpunit.xml and configure your Last.fm API key, then run:

composer test

🤝 Contributing

Issues and pull requests are welcome for bug fixes, features, and documentation.
Please see CONTRIBUTING.md and CODE OF CONDUCT for details.

🔒 Security

If you discover a security vulnerability, please email thatobabusi@yahoo.com instead of using the issue tracker.

📜 License

Open-sourced software licensed under the MIT license.
Built with ❤️ for the Laravel community.

thatobabusi / laravel-lastfm

Maintainers

Package info

Statistics

Security