README

This is a PHP wrapper for Tidal's API. It is a modified version of jwilsson/spotify-web-api-php.

Warning

This package currently only supports the official Tidal's API endpoints.

Table of Contents

1. Introduction
2. Version Compatability
3. Requirements
4. Installation
5. Usage
6. Changelog
7. Contributing
8. Security Vulnerabilities
9. Credits
10. License

Version Compatability

Requirements

• PHP 8.0 or later.
• PHP cURL extension (Usually included with PHP).

Installation

You can install the package via composer:

composer require gerenuk/php-tidal-api

Usage

Before using the Tidal API you will need to create an app at Tidal's developer website.

Simple example to retrieve the currently authenticated user's playlists:

Step 1:

Put the following code in its own file, lets call it auth.php. Replace CLIENT_ID with the value given to you by Tidal. The REDIRECT_URI is the one you entered when creating the Tidal app, make sure it's an exact match. You'll also need to create a code verifier and store it somewhere between requests. It will be used again in the second step.

require 'vendor/autoload.php';

$session = new TidalApi\Session(
    'CLIENT_ID',
    '', // Normally the client secret, but this value can be omitted when using the PKCE flow.
    'REDIRECT_URI'
);

$verifier = $session->generateCodeVerifier(); // Store this value somewhere, a session for example.
$challenge = $session->generateCodeChallenge($verifier);
$state = $session->generateState();

$options = [
    'code_challenge' => $challenge,
    'scope' => [
        'playlists.read',
    ],
    'state' => $state,
];

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

Note: The state parameter is optional but highly recommended to prevent CSRF attacks. The value will need to be stored between requests and verified when the user is redirected back to your application from Tidal.

Step 2:

When the user has approved your app, Tidal will redirect the user together with a code to the specified redirect URI. You'll need to use this code to request an access token from Tidal. The code verifier created in the previous step will also be needed.

Note: The API wrapper does not include any token management. It's up to you to save the access token somewhere (in a database, a PHP session, or wherever appropriate for your application) and request a new access token when the old one has expired.

Let's put this code in a new file called callback.php:

require 'vendor/autoload.php';

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

$state = $_GET['state'];

// Fetch the stored state value from somewhere. A session for example.

if ($state !== $storedState) {
    // The state returned isn't the same as the one we've stored, we shouldn't continue.
    die('State mismatch');
}

// Request an access token using the code from Tidal and the previously created code verifier.
$session->requestAccessToken($_GET['code'], $verifier);

$accessToken = $session->getAccessToken();
$refreshToken = $session->getRefreshToken();

// Store the access and refresh tokens somewhere. In a session for example.

// Send the user along and fetch some data!
header('Location: app.php');
die();

When requesting an access token, a refresh token will also be included. This can be used to extend the validity of access tokens. It's recommended to also store this somewhere persistent, in a database for example.

Step 3:

In a third file, app.php, tell the API wrapper which access token to use, and then make some API calls!

require 'vendor/autoload.php';

$api = new TidalApi\TidalApi();

// Fetch the saved access token from somewhere. A session for example.
$api->setAccessToken($accessToken);

// It's now possible to request the currently authenticated user's playlists.
print_r(
    $api->getMyPlaylists()
);

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Modified version of spotify-web-api-php from jwilsson
• Kieran Proctor
• All Contributors

License

The MIT License (MIT). Please see License File for more information.