spotify-web-api-php: a PHP wrapper that handles tokens and rate limits for you

What the wrapper covers

The library is a PHP wrapper for Spotify's Web API, and the coverage it lists is broad. There are helper methods for all API endpoints, grouped by what they act on: information about artists, albums, tracks, podcasts, audiobooks and users, the list of music featured by Spotify, playlist and user music library management, catalog search, and user playback control. That last group is worth noting, because controlling playback is a different kind of permission from reading metadata, and a wrapper that offers it as a first-class method group saves you from assembling the call yourself. What the library does not do is change Spotify's API. It does not extend the endpoint set, it does not add fields Spotify does not return, and it does not cache. What it adds is a PHP-shaped interface, the OAuth handling, and the two operational behaviours described below.

The two behaviours that save the most code

Automatic refreshing of access tokens and automatic retry of rate limited requests are the two features that justify a wrapper more than endpoint sugar does. A token that expires mid-request is a failure mode that only appears in production, and handling it by hand means catching an error, re-running the refresh and replaying the original call. Rate limiting is the other one, where a burst of requests gets a client into a state where it must back off, and the retry logic has to be attached to every call site. The wrapper attaches both centrally, which means the behaviour is consistent across your codebase rather than dependent on whether the developer who wrote a given endpoint remembered to handle it. This is also where the difference between a wrapper and a hand-rolled HTTP client shows up: the HTTP client does what you tell it, the wrapper anticipates the two failure modes the Spotify API actually produces.

Installing with Composer and the PHP floor

Installation is a single Composer requirement, and the library states its requirements plainly before that: PHP 8.3 or later, and the PHP cURL extension, which it notes is usually included with PHP.

composer require jwilsson/spotify-web-api-php

The PHP 8.3 floor is worth reading twice, because it is a real constraint rather than a formality. It rules out the long-lived distribution branches that many production PHP applications still run, and it means the library will not install on a host where the runtime is managed by a hosting provider you do not control. PSR-4 autoloading support is listed among the included features, which is what makes the Composer route the natural one, and the repository ships a composer.json at the root along with a src directory holding the classes and a tests directory. The repository also carries a CHANGELOG.md, a phpunit.dist.xml and a phpunit.php for the test configuration, and a .php-cs-fixer.dist.php for the coding style rules, so the project keeps its conventions in files rather than in a wiki page.

The authorization flow in one file

Before any of this works you need an app created at Spotify's developer site. The example the README gives is a single PHP file that does the whole redirect flow. A session object is constructed with a client id, a client secret and a redirect URI, an API object is created, and then the code branches on whether an authorization code came back in the query string. If it did, the session exchanges it for an access token and the token is handed to the API object before calling me(). If it did not, the code assembles the scope list and redirects the browser to the authorize URL, then stops.

require 'vendor/autoload.php';

$session = new SpotifyWebAPI\Session(
    'CLIENT_ID',
    'CLIENT_SECRET',
    'REDIRECT_URI'
);

$api = new SpotifyWebAPI\SpotifyWebAPI();

if (isset($_GET['code'])) {
    $session->requestAccessToken($_GET['code']);
    $api->setAccessToken($session->getAccessToken());

    print_r($api->me());
} else {
    $options = [
        'scope' => [
            'user-read-email',
        ],
    ];

    header('Location: ' . $session->getAuthorizeUrl($options));
    die();
}

The shape is the standard authorization code flow, and the wrapper does not change it. The scope array is the part you will edit most, since it determines what the granted token can do.

The scope list decides what the token can do

In the example the scope list contains a single entry, user-read-email, because the example calls me() and prints the result. Every additional capability your application wants, from reading a playlist to controlling playback, arrives as another scope string in that array. The practical consequence is that scopes are a design decision made at the redirect, and a missing scope shows up later as a rejected call rather than as a compile error. Because the access token is derived from the scopes granted at that moment, adding a capability later means sending the user through the authorize URL again. The wrapper's job is to build that URL correctly from the session and the options you pass to getAuthorizeUrl; it does not decide what you should ask for. The README also points at the Spotify Web API Console as a place to try out API calls directly, which is the fastest way to find out which scope a given endpoint needs before you change your redirect.

Two session objects, one API object

The example separates responsibilities in a way that is worth understanding rather than copying. The Session object owns the credentials and the token: it holds the client id, secret and redirect URI, it performs the exchange in requestAccessToken, it hands the token back through getAccessToken, and it builds the authorize URL from the scope options. The SpotifyWebAPI object owns the calls: you give it a token with setAccessToken and then call methods on it, such as me(). Keeping the token holder and the caller apart is what makes it possible to use the API object with a token you obtained some other way, for instance a refresh token flow you wrote yourself, and it means the API object holds no credentials of its own. The class names are namespaced under SpotifyWebAPI, so the two do not collide with anything else in a larger application.

Where this wrapper is the wrong choice

Three cases argue against it. First, if your application is not written in PHP, since this is a PHP library and not a service. Second, if you are on PHP 8.2 or earlier and cannot move, since the stated requirement is PHP 8.3 or later and the composer install will refuse. Third, if you need something the Spotify API itself does not expose, because the wrapper adds convenience, not capability, and there is no endpoint that the underlying API lacks. A structural point applies to versioning as well. The repository has no GitHub releases, so there is no tag history to pin against and no release notes to diff when an upgrade changes behaviour, though the CHANGELOG.md at the root is the place to look for that history. The last push to the repository was on 2026-07-25, and the project publishes to Packagist, whose version badge sits at the top of the README, so the Composer registry is the more reliable signal of what is current. The licence field on the repository says MIT.

Editorial conclusion

Use spotify-web-api-php when your PHP application needs to read or control Spotify on a user's behalf, because the authorization redirect dance and the token refresh cycle are the parts you would otherwise reimplement in every project. Do not adopt it for a static build-time integration or for a project still on PHP below 8.3, since the library states PHP 8.3 or later as its requirement. Verify first that your app is registered at Spotify's developer site and that the redirect URI you pass to the session matches the one registered there exactly, then read the composer.json and the docs directory for the endpoint list before you assume a call exists, since the repository has no tagged releases to guide you on version changes.

Frequently asked questions

Official sources

1. Issues
2. jwilsson/spotify-web-api-php on GitHub
3. License: MIT
4. README