Search API: Updated handling of parent detail, added testing

Review of #5280.

- Removed additional non-needed loads which could ignore permissions.
- Updated new formatter method name to be more specific on use.
- Added test case to cover changes.
- Updated API examples to align parent id/info in info to be
  representative.

app/Api/ApiEntityListFormatter.php

@@ -2,6 +2,7 @@
 
 namespace BookStack\Api;
 
+use BookStack\Entities\Models\BookChild;
 use BookStack\Entities\Models\Entity;
 use BookStack\Entities\Models\Page;
 
@@ -72,20 +73,20 @@ class ApiEntityListFormatter
     }
 
     /**
-     * Enable the inclusion of related book and chapter titles in the response.
+     * Include parent book/chapter info in the formatted data.
      */
-    public function withRelatedData(): self
+    public function withParents(): self
     {
         $this->withField('book', function (Entity $entity) {
-            if (method_exists($entity, 'book')) {
+            if ($entity instanceof BookChild && $entity->book) {
-                return $entity->book()->select(['id', 'name', 'slug'])->first();
+                return $entity->book->only(['id', 'name', 'slug']);
             }
             return null;
         });
 
         $this->withField('chapter', function (Entity $entity) {
-            if ($entity instanceof Page && $entity->chapter_id) {
+            if ($entity instanceof Page && $entity->chapter) {
-                return $entity->chapter()->select(['id', 'name', 'slug'])->first();
+                return $entity->chapter->only(['id', 'name', 'slug']);
             }
             return null;
         });
@@ -99,8 +100,6 @@ class ApiEntityListFormatter
      */
     public function format(): array
     {
-        $this->loadRelatedData();
-
         $results = [];
 
         foreach ($this->list as $item) {
@@ -110,23 +109,6 @@ class ApiEntityListFormatter
         return $results;
     }
 
-    /**
-     * Eager load the related book and chapter data when needed.
-     */
-    protected function loadRelatedData(): void
-    {
-        $pages = collect($this->list)->filter(fn($item) => $item instanceof Page);
-
-        foreach ($this->list as $entity) {
-            if (method_exists($entity, 'book')) {
-                $entity->load('book');
-            }
-            if ($entity instanceof Page && $entity->chapter_id) {
-                $entity->load('chapter');
-            }
-        }
-    }
-
     /**
      * Format a single entity item to a plain array.
      */

app/Search/SearchApiController.php

@@ -9,9 +9,6 @@ use Illuminate\Http\Request;
 
 class SearchApiController extends ApiController
 {
-    protected SearchRunner $searchRunner;
-    protected SearchResultsFormatter $resultsFormatter;
-
     protected $rules = [
         'all' => [
             'query' => ['required'],
@@ -20,10 +17,10 @@ class SearchApiController extends ApiController
         ],
     ];
 
-    public function __construct(SearchRunner $searchRunner, SearchResultsFormatter $resultsFormatter)
+    public function __construct(
-    {
+        protected SearchRunner $searchRunner,
-        $this->searchRunner = $searchRunner;
+        protected SearchResultsFormatter $resultsFormatter
-        $this->resultsFormatter = $resultsFormatter;
+    ) {
     }
 
     /**
@@ -50,7 +47,7 @@ class SearchApiController extends ApiController
         $this->resultsFormatter->format($results['results']->all(), $options);
 
         $data = (new ApiEntityListFormatter($results['results']->all()))
-            ->withType()->withTags()->withRelatedData()
+            ->withType()->withTags()->withParents()
             ->withField('preview_html', function (Entity $entity) {
                 return [
                     'name' => (string) $entity->getAttribute('preview_name'),

dev/api/responses/search-all.json

@@ -8,7 +8,7 @@
       "created_at": "2021-11-14T15:57:35.000000Z",
       "updated_at": "2021-11-14T15:57:35.000000Z",
       "type": "chapter",
-            "url": "https://example.com/books/my-book/chapter/a-chapter-for-cats",
+      "url": "https://example.com/books/cats/chapter/a-chapter-for-cats",
       "book": {
         "id": 1,
         "name": "Cats",
@@ -31,14 +31,14 @@
       "created_at": "2021-05-15T16:28:10.000000Z",
       "updated_at": "2021-11-14T15:56:49.000000Z",
       "type": "page",
-            "url": "https://example.com/books/my-book/page/the-hows-and-whys-of-cats",
+      "url": "https://example.com/books/cats/page/the-hows-and-whys-of-cats",
       "book": {
         "id": 1,
         "name": "Cats",
         "slug": "cats"
       },
       "chapter": {
-                "id": 84,
+        "id": 75,
         "name": "A chapter for cats",
         "slug": "a-chapter-for-cats"
       },
@@ -70,16 +70,16 @@
       "created_at": "2020-11-29T21:55:07.000000Z",
       "updated_at": "2021-11-14T16:02:39.000000Z",
       "type": "page",
-            "url": "https://example.com/books/my-book/page/how-advanced-are-cats",
+      "url": "https://example.com/books/big-cats/page/how-advanced-are-cats",
       "book": {
-                "id": 1,
+        "id": 13,
-                "name": "Cats",
+        "name": "Big Cats",
-                "slug": "cats"
+        "slug": "big-cats"
       },
       "chapter": {
-                "id": 84,
+        "id": 73,
-                "name": "A chapter for cats",
+        "name": "A chapter for bigger cats",
-                "slug": "a-chapter-for-cats"
+        "slug": "a-chapter-for-bigger-cats"
       },
       "preview_html": {
         "name": "How advanced are <strong>cats</strong>?",

tests/Api/SearchApiTest.php

@@ -13,7 +13,7 @@ class SearchApiTest extends TestCase
 {
     use TestsApi;
 
-    protected $baseEndpoint = '/api/search';
+    protected string $baseEndpoint = '/api/search';
 
     public function test_all_endpoint_returns_search_filtered_results_with_query()
     {
@@ -74,4 +74,46 @@ class SearchApiTest extends TestCase
         $resp = $this->actingAsApiEditor()->get($this->baseEndpoint . '?query=myqueryvalue');
         $resp->assertOk();
     }
+
+    public function test_all_endpoint_includes_parent_details_where_visible()
+    {
+        $page = $this->entities->pageWithinChapter();
+        $chapter = $page->chapter;
+        $book = $page->book;
+
+        $page->update(['name' => 'name with superextrauniquevalue within']);
+        $page->indexForSearch();
+
+        $editor = $this->users->editor();
+        $this->actingAsApiEditor();
+        $resp = $this->getJson($this->baseEndpoint . '?query=superextrauniquevalue');
+        $resp->assertJsonFragment([
+            'id' => $page->id,
+            'type' => 'page',
+            'book' => [
+                'id' => $book->id,
+                'name' => $book->name,
+                'slug' => $book->slug,
+            ],
+            'chapter' => [
+                'id' => $chapter->id,
+                'name' => $chapter->name,
+                'slug' => $chapter->slug,
+            ],
+        ]);
+
+        $this->permissions->disableEntityInheritedPermissions($chapter);
+        $this->permissions->setEntityPermissions($page, ['view'], [$editor->roles()->first()]);
+
+        $resp = $this->getJson($this->baseEndpoint . '?query=superextrauniquevalue');
+        $resp->assertJsonPath('data.0.id', $page->id);
+        $resp->assertJsonPath('data.0.book.name', $book->name);
+        $resp->assertJsonMissingPath('data.0.chapter');
+
+        $this->permissions->disableEntityInheritedPermissions($book);
+
+        $resp = $this->getJson($this->baseEndpoint . '?query=superextrauniquevalue');
+        $resp->assertJsonPath('data.0.id', $page->id);
+        $resp->assertJsonMissingPath('data.0.book.name');
+    }
 }