Add support for timestamped_ids to SpotifyWebAPI::addMyTracks()

Author: jwilsson

docs/examples/managing-user-library.md

@@ -22,12 +22,44 @@ It's also possible to list the albums, podcast episodes, or podcast shows in a u
 
 ```php
 $api->addMyTracks([
-    'TRACK_ID',
-    'TRACK_ID',
+    'ids' => [
+        'TRACK_ID',
+        'TRACK_ID',
+    ],
+]);
+```
+
+```php
+$api->addMyTracks([
+    'timestamped_ids' => [
+        ['id' => 'TRACK_ID', 'added_at' => '2025-10-01T11:00:00.000Z'],
+        ['id' => 'TRACK_ID', 'added_at' => '2025-10-01T12:00:00.000Z'],
+    ],
 ]);
 ```
 
-It's also possible to add an album, a podcast episode, or a podcast show to a user's library using `addMyAlbums`, `addMyEpisodes`, or `addMyShows`.
+## Adding albums, episodes, or shows to a user's library
+
+```php
+$api->addMyAlbums([
+    'ALBUM_ID',
+    'ALBUM_ID',
+]);
+```
+
+```php
+$api->addMyEpisodes([
+    'EPISODE_ID',
+    'EPISODE_ID',
+]);
+```
+
+```php
+$api->addMyShows([
+    'SHOW_ID',
+    'SHOW_ID',
+]);
+```
 
 ## Deleting tracks from a user's library
 

docs/method-reference/SpotifyWebAPI.md

@@ -175,7 +175,9 @@ Add tracks to the current user's Spotify library.<br>
 https://developer.spotify.com/documentation/web-api/reference/save-tracks-user
 
 #### Arguments
-* `$tracks` **string\|array** - Track IDs or URIs to add.
+* `$tracks` **array\|object** - Track IDs or URIs to add. One of "ids" or "timestamped_ids" key must be present.
+    * array ids Optional. An array of track IDs or URIs.
+    * array timestamped_ids Optional. An array of objects containing track IDs or URIs and added_at timestamp.
 
 #### Return values
 * **bool** Whether the tracks was successfully added.

src/SpotifyWebAPI.php

@@ -260,24 +260,51 @@ public function addMyShows(string|array $shows): bool
      * Add tracks to the current user's Spotify library.
      * https://developer.spotify.com/documentation/web-api/reference/save-tracks-user
      *
-     * @param string|array $tracks Track IDs or URIs to add.
+     * @param array|object $tracks Track IDs or URIs to add. One of "ids" or "timestamped_ids" key must be present.
+     * - array ids Optional. An array of track IDs or URIs.
+     * - array timestamped_ids Optional. An array of objects containing track IDs or URIs and added_at timestamp.
      *
      * @return bool Whether the tracks was successfully added.
      */
-    public function addMyTracks(string|array $tracks): bool
+    public function addMyTracks(string|array|object $tracks): bool
     {
-        $tracks = $this->uriToId($tracks, 'track');
-        $tracks = json_encode([
-            'ids' => (array) $tracks,
-        ]);
+        $tracks = is_object($tracks) ? (array) $tracks : $tracks;
+
+        if (is_array($tracks) && isset($tracks['ids'])) {
+            $tracks = (array) $this->uriToId($tracks['ids'], 'track');
+            $options = json_encode([
+                'ids' => $tracks,
+            ]);
+        } elseif (is_array($tracks) && isset($tracks['timestamped_ids'])) {
+            $tracks = array_map(function ($item) {
+                $item['id'] = $this->uriToId($item['id'], 'track');
+
+                return $item;
+            }, $tracks['timestamped_ids']);
+
+            $options = json_encode([
+                'timestamped_ids' => $tracks,
+            ]);
+        } else {
+            trigger_error(
+                // phpcs:ignore
+                'Passing string or array without "ids" or "timestamped_ids" key to SpotifyWebAPI::addMyTracks() is deprecated',
+                E_USER_DEPRECATED
+            );
+
+            $tracks = (array) $this->uriToId($tracks, 'track');
+            $options = json_encode([
+                'ids' => $tracks,
+            ]);
+        }
 
         $headers = [
             'Content-Type' => 'application/json',
         ];
 
         $uri = '/v1/me/tracks';
 
-        $this->lastResponse = $this->sendRequest('PUT', $uri, $tracks, $headers);
+        $this->lastResponse = $this->sendRequest('PUT', $uri, $options, $headers);
 
         return $this->lastResponse['status'] == 200;
     }

tests/SpotifyWebAPITest.php

@@ -222,7 +222,73 @@ public function testAddMyShows()
         );
     }
 
-    public function testAddMyTracks()
+    public function testAddMyTracksIds()
+    {
+        $tracks = [
+            'ids' => [
+                '1id6H6vcwSB9GGv9NXh5cl',
+                '3mqRLlD9j92BBv1ueFhJ1l',
+                'spotify:track:1id6H6vcwSB9GGv9NXh5cl',
+            ],
+        ];
+
+        $expected = json_encode([
+            'ids' => [
+                '1id6H6vcwSB9GGv9NXh5cl',
+                '3mqRLlD9j92BBv1ueFhJ1l',
+                '1id6H6vcwSB9GGv9NXh5cl',
+            ],
+        ]);
+
+        $headers = ['Content-Type' => 'application/json'];
+        $return = ['status' => 200];
+        $api = $this->setupApi(
+            'PUT',
+            '/v1/me/tracks',
+            $expected,
+            $headers,
+            $return
+        );
+
+        $this->assertTrue(
+            $api->addMyTracks($tracks)
+        );
+    }
+
+    public function testAddMyTracksTimestampedIds()
+    {
+        $tracks = [
+            'timestamped_ids' => [
+                ['id' => '1id6H6vcwSB9GGv9NXh5cl', 'added_at' => '2025-10-01T10:00:00.000Z'],
+                ['id' => '3mqRLlD9j92BBv1ueFhJ1l', 'added_at' => '2025-10-01T11:00:00.000Z'],
+                ['id' => 'spotify:track:1id6H6vcwSB9GGv9NXh5cl', 'added_at' => '2025-10-01T12:00:00.000Z'],
+            ],
+        ];
+
+        $expected = json_encode([
+            'timestamped_ids' => [
+                ['id' => '1id6H6vcwSB9GGv9NXh5cl', 'added_at' => '2025-10-01T10:00:00.000Z'],
+                ['id' => '3mqRLlD9j92BBv1ueFhJ1l', 'added_at' => '2025-10-01T11:00:00.000Z'],
+                ['id' => '1id6H6vcwSB9GGv9NXh5cl', 'added_at' => '2025-10-01T12:00:00.000Z'],
+            ],
+        ]);
+
+        $headers = ['Content-Type' => 'application/json'];
+        $return = ['status' => 200];
+        $api = $this->setupApi(
+            'PUT',
+            '/v1/me/tracks',
+            $expected,
+            $headers,
+            $return
+        );
+
+        $this->assertTrue(
+            $api->addMyTracks($tracks)
+        );
+    }
+
+    public function testAddMyTracksDeprecated()
     {
         $tracks = [
             '1id6H6vcwSB9GGv9NXh5cl',