README

Spotify for Laravel

An easy to use Spotify Web API wrapper for Laravel

Installation • Usage Example • Optional Parameters • Spotify API Reference •

Introduction

Spotify for Laravel makes working with the Spotify Web API a breeze. It provides straight forward methods for each endpoint and a fluent interface for optional parameters.

The package supports all Spotify Web API endpoints that are accessible with the Client Credentials Flow.

Installation

Install the package using Composer. The package will automatically register itself.

composer require aerni/laravel-spotify

Publish the config of the package.

php artisan vendor:publish --provider="Aerni\Spotify\Providers\SpotifyServiceProvider"

The following config will be published to config/spotify.php.

return [

    /*
    |--------------------------------------------------------------------------
    | Authentication
    |--------------------------------------------------------------------------
    |
    | The Client ID and Client Secret of your Spotify App.
    |
    */

    'auth' => [
        'client_id' => env('SPOTIFY_CLIENT_ID'),
        'client_secret' => env('SPOTIFY_CLIENT_SECRET'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Default Config
    |--------------------------------------------------------------------------
    |
    | You may define a default country, locale and market that will be used
    | for your Spotify API requests.
    |
    */

    'default_config' => [
        'country' => null,
        'locale' => null,
        'market' => null,
    ],

];

Set the Client ID and Client Secret of your Spotify App in your .env file.

SPOTIFY_CLIENT_ID=********************************
SPOTIFY_CLIENT_SECRET=********************************

Usage Example

Import the package at the top of your file. All of the following examples use the Facade.

use Aerni\Spotify\Facades\Spotify;

Search for tracks with the name Closed on Sunday.

Spotify::searchTracks('Closed on Sunday')->get();

Important: The get() method acts as the final method of the fluent interface. Make sure to always call it last in the method chain to execute a request to the Spotify Web API.

Optional Parameters

You may pass optional parameters to your requests using the fluent interface provided by this package. A common use case is to set a limit and offset to your request.

Spotify::searchTracks('Closed on Sunday')->limit(50)->offset(50)->get();

Parameter Methods API Reference

Consult the Spotify Web API Reference Documentation to check which parameters are available to what endpoint.

// Limit the response to a particular geographical market.
Spotify::artistAlbums('artist_id')->country('US')->get();

// Filter the query using the provided string.
Spotify::playlist('playlist_id')->fields('description, uri')->get();

// Include any relevant content that is hosted externally.
Spotify::searchTracks('query')->includeExternal('audio')->get();

// Filter the response using the provided string.
Spotify::artistAlbums('artist_id')->includeGroups('album, single, appears_on, compilation')->get();

// Set the number of track objects to be returned.
Spotify::searchTracks('query')->limit(10)->get();

// Set the index of the first track to be returned.
Spotify::searchTracks('query')->offset(10)->get();

// Limit the response to a particular geographical market.
Spotify::searchAlbums('query')->market('US')->get();

// Limit the response to a particular language.
Spotify::category('category_id')->locale('en_US')->get();

Resetting Defaults

You may want to reset the default setting of country, locale or market for a given request. You may do so by calling the corresponding parameter method with an empty argument.

// This will reset the default market to nothing.
Spotify::searchTracks('query')->market()->get();

Response Key

Some API responses are wrapped in a top level object like artists or tracks. If you want to directly access the content of a given top level object, you may do so by passing its key as a string to the get() method.

// This will return the content of the tracks object.
Spotify::searchTracks('query')->get('tracks');

Spotify API Reference

Note: Any parameter that accepts multiple values can either receive a string with comma-separated values or an array of values.

// Pass a string with comma-separated values
Spotify::albums('album_id, album_id_2, album_id_3')->get();

// Or pass an array of values
Spotify::albums(['album_id', 'album_id_2', 'album_id_3'])->get();

Albums

// Get an album by ID.
Spotify::album('album_id')->get();

// Get several albums by IDs. Provide a string or array of IDs.
Spotify::albums('album_id, album_id_2, album_id_3')->get();

// Get the tracks of an album by ID.
Spotify::albumTracks('album_id')->get();

Artists

// Get an artist by ID.
Spotify::artist('artist_id')->get();

// Get several artists by IDs. Provide a string or array of IDs.
Spotify::artists('artist_id, artist_id_2, artist_id_3')->get();

// Get albums of an artist by ID.
Spotify::artistAlbums('artist_id')->get();

// Get the artist's top tracks by ID.
Spotify::artistTopTracks('artist_id')->get();

Browse

// Get a category by ID.
Spotify::category('category_id')->get();

// Get a list of categories.
Spotify::categories()->get();

// Get a list of new releases.
Spotify::newReleases()->get();

Episodes

// Get an episode by ID.
Spotify::episode('episode_id')->get();

// Get several episodes by IDs. Provide a string or array of IDs.
Spotify::episodes('episode_id, episode_id_2, episode_id_3')->get();

Playlists

// Get a playlist by ID.
Spotify::playlist('playlist_id')->get();

// Get a playlist's tracks by ID.
Spotify::playlistTracks('playlist_id')->get();

// Get a playlist's cover image by ID.
Spotify::playlistCoverImage('playlist_id')->get();

Search

// Search items by query. Provide a string or array to the second parameter.
Spotify::searchItems('query', 'album, artist, playlist, track')->get();

// Search albums by query.
Spotify::searchAlbums('query')->get();

// Search artists by query.
Spotify::searchArtists('query')->get();

// Search episodes by query.
Spotify::searchEpisodes('query')->get();

// Search playlists by query.
Spotify::searchPlaylists('query')->get();

// Search shows by query.
Spotify::searchShows('query')->get();

// Search tracks by query.
Spotify::searchTracks('query')->get();

Shows

// Get a show by ID.
Spotify::show('show_id')->get();

// Get several shows by IDs. Provide a string or array of IDs.
Spotify::shows('show_id, show_id_2, show_id_3')->get();

// Get the episodes of a show by ID.
Spotify::showEpisodes('show_id')->get();

Tracks

// Get a track by ID.
Spotify::track('track_id')->get();

// Get several tracks by IDs. Provide a string or array of IDs.
Spotify::tracks('track_id, track_id_2, track_id_3')->get();

User's Profile

// Get a user's profile
Spotify::user('user_id')->get();

// Get a list of a user's playlists
Spotify::userPlaylists('user_id')->get();

Tests

Run the tests like this:

vendor/bin/phpunit