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.