Deprecate SpotifyWebAPI::usersFollowPlaylist()

Author: jwilsson

docs/examples/following-artists-playlists-and-users.md

@@ -34,17 +34,10 @@ $api->followPlaylist('PLAYLIST_ID');
 $api->unfollowPlaylist('PLAYLIST_ID');
 ```
 
-## Checking if user(s) are following a playlist
+## Checking if the current user is following a playlist
 
 ```php
-$users = [
-    'USER_1',
-    'USER_2',
-];
-
-$api->usersFollowsPlaylist('PLAYLIST_ID', [
-    'ids' => $users,
-]);
+$api->currentUserFollowsPlaylist('PLAYLIST_ID');
 ```
 
 Please see the [method reference](/docs/method-reference/SpotifyWebAPI.md) for more available options for each method.

docs/method-reference/SpotifyWebAPI.md

@@ -11,6 +11,7 @@
 * [changeVolume](#changevolume)
 * [createPlaylist](#createplaylist)
 * [currentUserFollows](#currentuserfollows)
+* [currentUserFollowsPlaylist](#currentuserfollowsplaylist)
 * [deleteMyAlbums](#deletemyalbums)
 * [deleteMyEpisodes](#deletemyepisodes)
 * [deleteMyShows](#deletemyshows)
@@ -277,6 +278,23 @@ https://developer.spotify.com/documentation/web-api/reference/check-current-user
 #### Return values
 * **array** Whether each user or artist is followed.
 
+---
+### currentUserFollowsPlaylist
+
+
+```php
+SpotifyWebAPI::currentUserFollowsPlaylist($playlistId)
+```
+
+Check if the current user is following a playlist.<br>
+https://developer.spotify.com/documentation/web-api/reference/check-if-user-follows-playlist
+
+#### Arguments
+* `$playlistId` **string** - ID or URI of the playlist to check.
+
+#### Return values
+* **array** Array containing one boolean describing whether the playlist is followed.
+
 ---
 ### deleteMyAlbums
 
@@ -1627,7 +1645,7 @@ Set the access token to use.
 * `$accessToken` **string** - The access token.
 
 #### Return values
-* **self**
+* **self** 
 
 ---
 ### setOptions
@@ -1643,7 +1661,7 @@ Set options
 * `$options` **array\|object** - Options to set.
 
 #### Return values
-* **self**
+* **self** 
 
 ---
 ### setSession
@@ -1659,7 +1677,7 @@ Set the Session object to use.
 * `$session` **\SpotifyWebAPI\Session** - The Session object.
 
 #### Return values
-* **self**
+* **self** 
 
 ---
 ### shuffle
@@ -1758,6 +1776,7 @@ https://developer.spotify.com/documentation/web-api/reference/upload-custom-play
 ---
 ### usersFollowPlaylist
 
+_Deprecated. Use SpotifyWebAPI::currentUserFollowsPlaylist() instead._
 
 ```php
 SpotifyWebAPI::usersFollowPlaylist($playlistId, $options)
@@ -1768,10 +1787,10 @@ https://developer.spotify.com/documentation/web-api/reference/check-if-user-foll
 
 #### Arguments
 * `$playlistId` **string** - ID or URI of the playlist.
-* `$options` **array\|object** - Options for the check.
-    * ids string\|array Required. IDs or URIs of the users to check for.
+* `$options` **array\|object** - Optional. Options for the check.
+    * ids string\|array ID or URI of the current user.
 
 #### Return values
-* **array** Whether each user is following the playlist.
+* **array** Whether the current user is following the playlist.
 
 ---

src/SpotifyWebAPI.php

@@ -433,6 +433,25 @@ public function currentUserFollows(string $type, string|array $ids): array
         return $this->lastResponse['body'];
     }
 
+    /**
+     * Check if the current user is following a playlist.
+     * https://developer.spotify.com/documentation/web-api/reference/check-if-user-follows-playlist
+     *
+     * @param string $playlistId ID or URI of the playlist to check.
+     *
+     * @return array Array containing one boolean describing whether the playlist is followed.
+     */
+    public function currentUserFollowsPlaylist(string $playlistId): array
+    {
+        $playlistId = $this->uriToId($playlistId, 'playlist');
+
+        $uri = '/v1/playlists/' . $playlistId . '/followers/contains';
+
+        $this->lastResponse = $this->sendRequest('GET', $uri);
+
+        return $this->lastResponse['body'];
+    }
+
     /**
      * Delete albums from the current user's Spotify library.
      * https://developer.spotify.com/documentation/web-api/reference/remove-albums-user
@@ -2234,14 +2253,22 @@ public function updatePlaylistImage(string $playlistId, string $imageData): bool
      * Check if a set of users are following a playlist.
      * https://developer.spotify.com/documentation/web-api/reference/check-if-user-follows-playlist
      *
+     * @deprecated Use SpotifyWebAPI::currentUserFollowsPlaylist() instead.
+     *
      * @param string $playlistId ID or URI of the playlist.
-     * @param array|object $options Options for the check.
-     * - ids string|array Required. IDs or URIs of the users to check for.
+     * @param array|object $options Optional. Options for the check.
+     * - ids string|array ID or URI of the current user.
      *
-     * @return array Whether each user is following the playlist.
+     * @return array Whether the current user is following the playlist.
      */
-    public function usersFollowPlaylist(string $playlistId, array|object $options): array
+    public function usersFollowPlaylist(string $playlistId, array|object $options = []): array
     {
+        trigger_error(
+            // phpcs:ignore
+            'SpotifyWebAPI::usersFollowPlaylist() is deprecated. Use SpotifyWebAPI::currentUserFollowsPlaylist() instead.',
+            E_USER_DEPRECATED
+        );
+
         $options = (array) $options;
 
         if (isset($options['ids'])) {

tests/SpotifyWebAPITest.php

@@ -432,6 +432,24 @@ public function testCurrentUserFollows()
         $this->assertTrue($response[0]);
     }
 
+    public function testCurrentUserFollowsPlaylist()
+    {
+        $return = ['body' => get_fixture('users-follows-playlist')];
+        $api = $this->setupApi(
+            'GET',
+            '/v1/playlists/0UZ0Ll4HJHR7yvURYbHJe9/followers/contains',
+            [],
+            [],
+            $return
+        );
+
+        $response = $api->currentUserFollowsPlaylist(
+            'spotify:playlist:0UZ0Ll4HJHR7yvURYbHJe9',
+        );
+
+        $this->assertTrue($response[0]);
+    }
+
     public function testDeleteMyAlbums()
     {
         $albums = [
@@ -2363,13 +2381,12 @@ public function testUsersFollowPlaylist()
     {
         $options = [
             'ids' => [
-                'possan',
-                'spotify:user:elogain',
+                'spotify:user:mcgurk',
             ],
         ];
 
         $expected = [
-            'ids' => 'possan,elogain',
+            'ids' => 'mcgurk',
         ];
 
         $return = ['body' => get_fixture('users-follows-playlist')];

tests/fixtures/users-follows-playlist.json

@@ -1 +1 @@
-[true, true]
+[true]