Download the PHP package aslamhus/spotify-client without Composer

Spotify API Client (PHP)

Overview

This PHP package provides a simple and convenient way to interact with the Spotify API. It includes methods for making authenticated requests, retrieving resources, and performing searches. The class utilizes the GuzzleHttp library for HTTP requests.

Installation

Usage

Authorization

Authorization is required to access different scopes of Spotify resources. Choose between Client Credentials and Authorization Code.

Client Credentials

For server-to-server authentication you can use Spotify's Client Credentials authorization flow. Simply pass your client id and secret to a SpotifyAccessToken, then inject the token into a new Spotify instance. The client id and secret can be found in your Spotify Dashboard. For security, it is recommended to store your client id and secret in environment variables.

Note: User information (like playlists) cannot be accessed with these credentials

Authorization Code

The authorization code flow is suitable for long-running applications (e.g. web and mobile apps) where the user grants permission only once.

By requesting authorization from the user, you can gain access to different scopes of Spotify resources.

Please refer to the Spotify docs for more on the Authorization Code flow: https://developer.spotify.com/documentation/web-api/tutorials/code-flow

This authorization has a two step process:

1. Request user authorization.

   Generate an authorization request url with the static method getAuthorizeUrl. Once the user is directed to this url, they will be prompted to give permissions to the scopes you specified. Once they grant permission, they will be redirected to the redirect uri you specified.

   Find a list of Spotify API scopes here.

   Note that the redirect uri must be set in your application's dashboard.

   When the user is redirected to the uri you have specified, save the code string from the query parameter.

2. Request access token

   You are now ready to request an access token with the user's granted permissions. Create a new AuthorizationCode credentials object with the code and redirect uri from the previous step. This will generate an access token with the appropriate permissions.

   Note: the redirect uri passed to AuthorizationCode must match exactly the redirect uri you specified in your application's dashboard and in the previous step.

Stored Token

If you have saved a token to the database, you can create a new AccessToken and pass that to Spotify.

Token expiration and refresh tokens

Spotify tokens are intentionally set to expire after 1 hour. If you have used the AuthorizationCode credentials, your token comes with a refresh token. Aslamhus\Spotify will automatically handle refreshing your token when you make a request.

Get Resource

Search

Search results are paginated. When you perform a search, you can get a SearchResult object for each type you've searched for, i.e. 'artist, track, album' would return a separate SearchResult object for each type.

Note: Search is currently only available for tracks, albums and artists

Basic search

Using queries with special characters

There is scant documentation on how to format Spotify API searches, but tests show it is best to urlencode your queries. For instance, searching for the track "Home Cookin' by Cory Weeds" will return no results if not urlencoded.

Get Search Items

Search Result Types

Each SearchResult object contains an array of search items. Depending on the given type you are searching for, each item in the array will be an entity object like Aritst or Album. If you are searching for tracks, instead of an array of Track objects, you will receieve the Tracks object, which functions like an array but with additional methods for managing and ssearching for tracks.

Get next results

Let's demonstrate how to get the next results. Each SearchResult object has a next method, which gets the next set of results if available. If there are no next results, next returns null.

Get all artist albums

Get all tracks for an album

Carrying on from the last example, we can now load the tracks any album.

Note that the data for entity objects like Album, Artist, and Track is lazy loaded. You have to explicitly fetch their data with the relevant get method.

Playlist

Get Playlist

IMPORTANT: Working with Playlist or User entities requires the AuthorizationCode credentials

This example assumes you know the id of the playlist.

Create a new playlist

The static method create is a factory function which returns a new instance of the Playlist entity.

Add Tracks

In order to add a track to a playlist you must know its track id. If you have previously loaded a Track or Tracks object with an id associated with it, you can simply add those.

Adding a single track

Adding a track to a specific index in the playlist

Adding multiple tracks

Remove Tracks

Unfollow a playlist

A note about deleting / unfollowing playlists from the Spotify API Docs:

"We have no endpoint for deleting a playlist in the Web API; the notion of deleting a playlist is not relevant within the Spotify’s playlist system. Even if you are the playlist’s owner and you choose to manually remove it from your own list of playlists, you are simply unfollowing it. Although this behavior may sound strange, it means that other users who are already following the playlist can keep enjoying it. Manually restoring a deleted playlist through the Spotify Accounts Service is the same thing as following one of your own playlists that you have previously unfollowed."

Additional playlist methods

Error Handling

If a non-200 status code is received, an exception is thrown with a descriptive error message.

Status Codes

The class includes a list of common Spotify API status codes along with descriptions for reference.

• 200 OK
• 201 Created
• 202 Accepted
• 204 No Content
• 304 Not Modified
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable

Contributing

Feel free to contribute by opening issues or submitting pull requests. Your feedback is valuable.

License

This package is open-source software licensed under the MIT License.