Mark Bookmark Methods as Deprecated (From Discussions #209)

src/Prismic/Api.php

@@ -151,6 +151,9 @@ public function getRefFromLabel(string $label) :? Ref
      * Returns the list of all bookmarks on the repository. If you're looking
      * for a document from it's bookmark name, you should use the bookmark() function.
      *
+     * @deprecated 5.4.0 This method will no longer work after the 12 February 2025,
+     * as bookmarks are removed from the API.
+     *
      * @return array the array of bookmarks
      */
     public function bookmarks() : array
@@ -165,6 +168,9 @@ public function bookmarks() : array
      * Most starter projects embed a helper to query a document from their ID string,
      * which makes this even easier.
      *
+     * @deprecated 5.4.0 This method will no longer work after the 12 February 2025,
+     * as bookmarks are removed from the API.
+     *
      * @param string $name the bookmark name to use
      *
      * @return string|null the ID string for a given bookmark name

src/Prismic/ApiData.php

@@ -16,6 +16,9 @@ class ApiData
 
     /**
      * An array of the available bookmarks
+     *
+     * @deprecated 5.4.0
+     *
      * @var array
      */
     private $bookmarks;
@@ -66,7 +69,7 @@ class ApiData
      * A constructor to build the object when you've retrieved all the data you need.
      *
      * @param array $refs
-     * @param array $bookmarks
+     * @param array $bookmarks (deprecated since 5.4.0)
      * @param array $types
      * @param array $languages
      * @param array $tags
@@ -131,7 +134,7 @@ function ($ref) {
                 },
                 $json->refs
             ),
-            (array)$json->bookmarks,
+            isset($json->bookmarks) ? (array)$json->bookmarks : [],
             (array)$json->types,
             array_map(
                 function ($language) {
@@ -158,6 +161,9 @@ public function getRefs() : array
 
     /**
      * Get the bookmarks
+     *
+     * @deprecated 5.4.0 This method will no longer work after the 12 February 2025,
+     * as bookmarks are removed from the API.
      */
     public function getBookmarks() : array
     {

tests/Prismic/ApiDataTest.php

@@ -36,6 +36,15 @@ public function testWithJsonStringThrowsExceptionForInvalidJson()
         ApiData::withJsonString('wtf?');
     }
 
+    public function testApiDataWorksWithoutBookmarks()
+    {
+        $json = $this->getJsonFixture('data-without-bookmarks.json');
+        $data = ApiData::withJsonString($json);
+
+        $this->assertInstanceOf(ApiData::class, $data);
+        $this->assertEquals([], $data->getBookmarks());
+    }
+
     public function testApiDataHasExpectedValues()
     {
         $this->assertCount(3, $this->data->getRefs());

tests/Prismic/ApiTest.php

@@ -201,6 +201,26 @@ public function testBookmarkReturnsCorrectDocumentId()
         $this->assertNull($api->bookmark('unknown-bookmark'));
     }
 
+    public function testApiWorksWithoutBookmarks()
+    {
+        // Create an ApiData object without bookmarks
+        $data = $this->getJsonFixture('data-without-bookmarks.json');
+        $apiData = ApiData::withJsonString($data);
+
+        // Cache the data
+        $key = 'https://whatever.prismic.io/api/v2#My-Access-Token';
+        $cachedData = serialize($apiData);
+        $this->cache->get($key)->willReturn($cachedData);
+        $this->httpClient->request()->shouldNotBeCalled();
+
+        $api = $this->getApi();
+
+        // Test that the bookmarks are empty
+        $this->assertEmpty($api->bookmarks());
+        $this->assertNull($api->bookmark('about'));
+        $this->assertNull($api->bookmark('unknown-bookmark'));
+    }
+
     public function testFormsReturnsOnlyFormInstances()
     {
         $api = $this->getApiWithDefaultData();

tests/fixtures/data-without-bookmarks.json

@@ -0,0 +1,165 @@
+{
+    "refs": [
+        {
+            "id": "master",
+            "ref": "UgjWQN_mqa8HvPJY",
+            "label": "Master",
+            "isMasterRef": true
+        },
+        {
+            "id": "UkL0hcuvzYUANCrr",
+            "ref": "UgjWRd_mqbYHvPJa",
+            "label": "San Francisco Grand opening"
+        },
+        {
+            "id": "SaGrandOpening2ndRef",
+            "ref": "SaGrandOpening2ndRef",
+            "label": "San Francisco Grand opening"
+        }
+    ],
+    "types": {
+        "blog-post": "Blog post",
+        "store": "Store",
+        "article": "Site-level article",
+        "selection": "Products selection",
+        "job-offer": "Job offer",
+        "product": "Product"
+    },
+    "languages": [
+        {
+            "id": "en-us",
+            "name": "English - United States"
+        },
+        {
+            "id": "nl-nl",
+            "name": "Dutch - Netherlands"
+        },
+        {
+            "id": "es-es",
+            "name": "Spanish - Spain (Traditional)"
+        },
+        {
+            "id": "fr-fr",
+            "name": "French - France"
+        }
+    ],
+    "tags": ["Cupcake", "Pie", "Featured", "Macaron"],
+    "forms": {
+        "everything": {
+            "method": "GET",
+            "enctype": "application/x-www-form-urlencoded",
+            "action": "http://lesbonneschoses.prismic.io/api/v2/documents/search",
+            "fields": {
+                "ref": {
+                    "type": "String"
+                },
+                "q": {
+                    "type": "String"
+                }
+            }
+        },
+        "blogs": {
+            "name": "Blog Posts",
+            "method": "GET",
+            "rel": "collection",
+            "enctype": "application/x-www-form-urlencoded",
+            "action": "https://lesbonneschoses.prismic.io/api/v2/documents/search",
+            "fields": {
+                "ref": {
+                    "type": "String",
+                    "multiple": false
+                },
+                "q": {
+                    "default": "[[:d = any(document.type, [\"blog-post\"])]]",
+                    "type": "String",
+                    "multiple": true
+                },
+                "lang": {
+                    "type": "String",
+                    "multiple": false
+                },
+                "page": {
+                    "type": "Integer",
+                    "multiple": false,
+                    "default": "1"
+                },
+                "pageSize": {
+                    "type": "Integer",
+                    "multiple": false,
+                    "default": "20"
+                },
+                "after": {
+                    "type": "String",
+                    "multiple": false
+                },
+                "fetch": {
+                    "type": "String",
+                    "multiple": false
+                },
+                "fetchLinks": {
+                    "type": "String",
+                    "multiple": false
+                },
+                "graphQuery": {
+                    "type": "String",
+                    "multiple": false
+                },
+                "orderings": {
+                    "type": "String",
+                    "multiple": false
+                },
+                "referer": {
+                  "type": "String",
+                  "multiple": false
+                },
+                "access_token": {
+                    "default": "a-permanent-access-token",
+                    "type": "String",
+                    "multiple": false
+                }
+            }
+        }
+    },
+    "oauth_initiate": "http://lesbonneschoses.prismic.io/auth",
+    "oauth_token": "http://lesbonneschoses.prismic.io/auth/token",
+    "experiments" : {
+        "draft": [
+            {
+                "id": "xxxxxxxxxxoGelsX",
+                "name": "Exp 2",
+                "variations": [
+                    {
+                        "id": "VDUBBawGAKoGelsZ",
+                        "label": "Base",
+                        "ref": "VDUBBawGALAGelsa"
+                    },
+                    {
+                        "id": "VDUE-awGALAGemME",
+                        "label": "var 1",
+                        "ref": "VDUUmHIKAZQKk9uq"
+                    }
+                ]
+            }
+        ],
+        "running": [
+            {
+                "googleId": "_UQtin7EQAOH5M34RQq6Dg",
+                "id": "VDUBBawGAKoGelsX",
+                "name": "Exp 1",
+                "variations": [
+                    {
+                        "id": "VDUBBawGAKoGelsZ",
+                        "label": "Base",
+                        "ref": "VDUBBawGALAGelsa"
+                    },
+                    {
+                        "id": "VDUE-awGALAGemME",
+                        "label": "var 1",
+                        "ref": "VDUUmHIKAZQKk9uq"
+                    }
+                ]
+            }
+        ]
+    }
+
+}