Laravel Spotify Laravel Package

Getting Started

Install the package with Composer, then publish the config if you need to adjust credentials:

composer install aerni/laravel-spotify
php artisan vendor:publish --tag="spotify-config"

On v3.0.0+, the import paths changed — make sure you're importing the facades directly:

use Aerni\Spotify\Facades\Spotify;
use Aerni\Spotify\Facades\SpotifyClient;

Spotify::searchItems('Track', 'Bohemian Rhapsody');

First things to check:

1. config/spotify.php — set client_id, client_secret, and redirect_uri. These map to your Spotify app credentials from the Spotify Developer Dashboard.
2. Facade choice — Spotify for the authenticated user's context (playlists, saved tracks, playback), SpotifyClient for app-level (client credentials) calls where no user scope is needed.
3. First use case — fetch a search result and a track in a tinker session or test route:

$tracks = Spotify::searchItems('Track', 'Daft Punk')->get();
$track  = Spotify::track('4cOdK2wGLETKBW3PvgPWqT')->get();

If auth fails, confirm the user has been through the OAuth flow via your app's authorization route (you own that flow — this package gives you the API client, not the OAuth dance).

Implementation Patterns

Client vs. user context. Use SpotifyClient (client credentials) for public catalog lookups — search, albums, artists, tracks. Use Spotify (user-scoped) when you need the authenticated user's library, playlists, or playback control. Mixing these up is the most common source of 401/403 errors.

Wrap API calls in a small service. Don't sprinkle facade calls through controllers. Create a SpotifyService that injects the facade or the underlying client, so you can mock it in tests and centralize error handling:

class SpotifyService
{
    public function topTracks(int $limit = 20): array
    {
        return Spotify::userTopItems('tracks', ['limit' => $limit])->get();
    }
}

Chained builder style. Methods return a request builder; call ->get() (or post methods where relevant) to execute. This makes it easy to compose parameters inline and to unit-test method calls without hitting the network.

Caching. Spotify rate-limits aggressively. Cache catalog responses (album, track, searchItems) with Cache::remember and a TTL appropriate to the resource. Playback state should not be cached.

Queued jobs. Playlist syncing, bulk track enrichments, and anything iterating over paginated results should run in a queued job. The offset/limit pagination pattern (limit capped at 50) means large playlists warrant a job with retry/backoff configured.

OAuth integration. Pair this with Laravel Socialite or a manual Spotify OAuth flow. Store the refresh token and access token on your User model; refresh before expiry. The package uses whatever token you hand it, so keep token lifecycle in your app layer.

Testing. Because the facade resolves to a single client, Spotify::shouldReceive('track')->andReturn(...) works, but consider an HTTP fake against the Spotify base URL for integration-level tests where the query string and auth header matter.

Gotchas and Tips

Upgrading to v3.0.0 is breaking if you used the removed endpoints. The following methods no longer exist and are gone from the Spotify Web API (affects newly created apps):

• artistRelatedArtists()
• categoryPlaylists()
• featuredPlaylists()
• recommendations()
• availableGenreSeeds()
• audioAnalysisForTrack()
• audioFeaturesForTrack()
• audioFeaturesForTracks()

If you depend on any of these — especially recommendations() — pin ^2.0 and do not upgrade. The SpotifySeed class is also gone.

Facade aliases are removed. Any old use Spotify; or use SpotifyClient; imports will fatal. Replace with:

- use Spotify;
+ use Aerni\Spotify\Facades\Spotify;

- use SpotifyClient;
+ use Aerni\Spotify\Facades\SpotifyClient;

Grep for both strings across app/, tests/, and any package-level service providers.

client credentials cannot touch user data. If you see a 403 on userTopItems, currentUserPlaylists, or playback methods, you're likely on SpotifyClient instead of Spotify. This is a common trap when refactoring.

Limit is capped at 50. limit above 50 is silently clamped by Spotify; the package doesn't warn you. For pagination, track offset yourself or use the next cursor the API returns.

Token expiry mid-request. Spotify tokens last ~1 hour. Implement a middleware/decorator that refreshes before the call, otherwise long-running queued jobs will fail partway through.

Debugging. Use Http::fake() in tests to inspect the outgoing request, and log the response body on non-2xx — Spotify returns useful error.message fields that the package surfaces but you may be swallowing in a generic catch.

Extension points. The facade is backed by a concrete client class you can bind to in a service provider; if you need custom retry logic or logging, bind your own wrapper rather than re-implementing the package's methods.

Version pinning. Given the v3 removals are tied to Spotify's own deprecation timeline, review this package's CHANGELOG before each minor bump — ^3.0 is safe for new integrations, but existing v2 codebases should upgrade deliberately and re-run integration tests around playback and playlist features.