diff --git a/src/Endpoint/Content.php b/src/Endpoint/Content.php index 4306e7d..29b4b2e 100755 --- a/src/Endpoint/Content.php +++ b/src/Endpoint/Content.php @@ -41,7 +41,7 @@ public function findPagesInSpace(string $spaceKey, int $limit = 2000, ?int $offs array_merge([ 'query' => array_filter([ 'spaceKey' => $spaceKey, - 'expand' => 'history.lastUpdated,metadata.labels,body.storage', + 'expand' => 'history.lastUpdated,metadata.labels,body.storage,ancestors,extensions.position', 'status' => 'current', 'start' => $offset, 'limit' => 200, @@ -62,7 +62,45 @@ public function findPagesInSpace(string $spaceKey, int $limit = 2000, ?int $offs $foundEntries += $content['size']; } while ($foundEntries <= $limit && $content['size'] >= $content['limit']); - return $pages; + return $this->sortByPageTree($pages); + } + + /** + * Orders the pages like the Confluence page tree: depth-first, siblings by manual + * position, unpositioned siblings by title. Pages whose parent is unknown become roots. + * + * @param array $pages + * @return array + */ + private function sortByPageTree(array $pages): array + { + $children = []; + foreach ($pages as $page) { + $parentId = $page->getParentId() ?? ''; + $children[isset($pages[$parentId]) ? $parentId : ''][] = $page; + } + + $sorted = []; + $this->appendSubtree('', $children, $sorted); + + return $sorted; + } + + /** + * @param array> $children + * @param array $sorted + */ + private function appendSubtree(string $parentId, array $children, array &$sorted): void + { + $siblings = $children[$parentId] ?? []; + usort($siblings, static fn (ConfluencePage $a, ConfluencePage $b): int => + [$a->getPosition() ?? PHP_INT_MAX, $a->getTitle()] <=> [$b->getPosition() ?? PHP_INT_MAX, $b->getTitle()]); + + foreach ($siblings as $page) { + $pageId = (string) $page->getId(); + $sorted[$pageId] = $page; + $this->appendSubtree($pageId, $children, $sorted); + } } /** diff --git a/src/Endpoint/Dto/ConfluencePage.php b/src/Endpoint/Dto/ConfluencePage.php index 4e9db0c..05b10cc 100755 --- a/src/Endpoint/Dto/ConfluencePage.php +++ b/src/Endpoint/Dto/ConfluencePage.php @@ -138,6 +138,28 @@ public function getLastUpdated(): ?DateTime return $this->lastUpdated; } + /** + * ID of the direct parent page, requires the `ancestors` expansion. + */ + public function getParentId(): ?string + { + $ancestors = $this->rawData['ancestors'] ?? []; + $parent = end($ancestors); + + return isset($parent['id']) ? (string) $parent['id'] : null; + } + + /** + * Manual position among its siblings, requires the `extensions.position` expansion. + * Null if the page was never moved manually (Confluence then sorts it by title). + */ + public function getPosition(): ?int + { + $position = $this->rawData['extensions']['position'] ?? null; + + return is_int($position) && $position >= 0 ? $position : null; + } + /** * @return array */ diff --git a/tests/Endpoint/ContentTest.php b/tests/Endpoint/ContentTest.php index 7d2a930..6bda5dc 100644 --- a/tests/Endpoint/ContentTest.php +++ b/tests/Endpoint/ContentTest.php @@ -85,6 +85,29 @@ public function testFindPagesInSpaceParsesPagesAndTerminatesOnAShortPage(): void self::assertSame('Page two', $pages['p2']->getTitle()); } + public function testFindPagesInSpaceReturnsPagesInPageTreeOrder(): void + { + $home = ['id' => '1']; + $json = json_encode([ + 'results' => [ + ['id' => '5', 'title' => 'Alpha', 'ancestors' => [$home], 'extensions' => ['position' => 'none']], + ['id' => '3', 'title' => 'Second', 'ancestors' => [$home], 'extensions' => ['position' => 2]], + ['id' => '6', 'title' => 'Orphan', 'ancestors' => [['id' => '99']]], + ['id' => '4', 'title' => 'Nested', 'ancestors' => [$home, ['id' => '2']]], + ['id' => '2', 'title' => 'First', 'ancestors' => [$home], 'extensions' => ['position' => 1]], + ['id' => '1', 'title' => 'Home', 'ancestors' => []], + ], + 'limit' => 200, + 'size' => 6, + ], JSON_THROW_ON_ERROR); + $content = $this->content(new Response(200, [], $json)); + + $titles = array_map(static fn (ConfluencePage $page): ?string => $page->getTitle(), $content->findPagesInSpace('SPACE')); + + self::assertSame(['Home', 'First', 'Nested', 'Second', 'Alpha', 'Orphan'], array_values($titles)); + self::assertSame([1, 2, 4, 3, 5, 6], array_keys($titles)); + } + public function testFindPageContentParsesASinglePage(): void { $json = json_encode([