Skip to content

Latest commit

 

History

History
443 lines (322 loc) · 13.9 KB

readme.md

File metadata and controls

443 lines (322 loc) · 13.9 KB
Raw


Spotify for Laravel

An easy to use Spotify Web API wrapper for Laravel 11

Packagist version Packagist total downloads GitHub license PayPal donate

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

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 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();

// Get results based on a specific date and time.
Spotify::featuredPlaylists()->timestamp('2020-03-02T09:00:00')->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

Spotify Web API Reference on 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

Spotify Web API Reference on 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();

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

Browse

Spotify Web API Reference on Browse

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

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

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

// Get a list of featured playlists.
Spotify::featuredPlaylists()->get();

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

// Get available genre seeds.
Spotify::availableGenreSeeds()->get();

// Get recommendations based on a seed.
Spotify::recommendations($seed)->get();

Episodes

Spotify Web API Reference on 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

Spotify Web API Reference on 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

Spotify Web API Reference on 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

Spotify Web API Reference on 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

Spotify Web API Reference on 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();

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

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

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

User's Profile

Spotify Web API Reference on 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();

Recommendations

You can get personalized tracks using the recommendations endpoint by seeding artists, genres and tracks along with a bunch of adjustable properties such as energy, key and danceability.

Usage Example

Import the SpotifySeed class. All of the following examples use the Facade.

use SpotifySeed;

Build your personalized $seed. You may chain as many methods as you want.

$seed = SpotifySeed::setGenres(['gospel', 'pop', 'funk'])
    ->setTargetValence(1.00)
    ->setSpeechiness(0.3, 0.9)
    ->setLiveness(0.3, 1.0);

Get your personalized tracks by passing the $seed to the recommendations() method.

Spotify::recommendations($seed)->get();

SpotifySeed API Reference

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

Add artists, genres and tracks to your seed:

// Add an artist by ID.
SpotifySeed::addArtist('artist_id');

// Add several artists by IDs. Provide a string or array of IDs.
SpotifySeed::addArtists('artist_id_1, artist_id_2, artist_id_3');

// Set artists by IDs. Provide a string or array of IDs. This overwrites previously added artists.
SpotifySeed::setArtists('artist_id_1, artist_id_2, artist_id_3');

// Add a genre by ID.
SpotifySeed::addGerne('gerne_id');

// Add several genres by IDs. Provide a string or array of IDs.
SpotifySeed::addGenres('gerne_id_1, gerne_id_2, gerne_id_3');

// Set gernes by IDs. Provide a string or array of IDs. This overwrites previously added genres.
SpotifySeed::setGenres('genre_id_1, genre_id_2, genre_id_3');

// Add a track by ID.
SpotifySeed::addTrack('track_id');

// Add several tracks by IDs. Provide a string or array of IDs.
SpotifySeed::addTracks('track_id_1, track_id_2, track_id_3');

// Set tracks by IDs. Provide a string or array of IDs. This overwrites previously added tracks.
SpotifySeed::setTracks('track_id_1, track_id_2, track_id_3');

Add tunable properties to your seed:

SpotifySeed::setAcousticness(float $min, float $max);
SpotifySeed::setTargetAcousticness(float $target);

SpotifySeed::setDanceability(float $min, float $max);
SpotifySeed::setTargetDanceability(float $target);

SpotifySeed::setDuration(int $min, int $max);
SpotifySeed::setTargetDuration(int $target);

SpotifySeed::setEnergy(float $min, float $max);
SpotifySeed::setTargetEnergy(float $target);

SpotifySeed::setInstrumentalness(float $min, float $max);
SpotifySeed::setTargetInstrumentalness(float $target);

SpotifySeed::setKey(int $min, int $max);
SpotifySeed::setTargetKey(int $target);

SpotifySeed::setLiveness(float $min, float $max);
SpotifySeed::setTargetLiveness(float $target);

SpotifySeed::setLoudness(float $min, float $max);
SpotifySeed::setTargetLoudness(float $target);

SpotifySeed::setMode(int $min, int $max);
SpotifySeed::setTargetMode(int $target);

SpotifySeed::setPopularity(float $min, float $max);
SpotifySeed::setTargetPopularity(float $target);

SpotifySeed::setSpeechiness(float $min, float $max);
SpotifySeed::setTargetSpeechiness(float $target);

SpotifySeed::setTempo(int $min, int $max);
SpotifySeed::setTargetTempo(int $target);

SpotifySeed::setTimeSignature(int $min, int $max);
SpotifySeed::setTargetTimeSignature(int $target);

SpotifySeed::setValence(float $min, float $max);
SpotifySeed::setTargetValence(float $target);

Tests

Run the tests like this:

vendor/bin/phpunit