* Option to get content children $client->content()->children()

* Option to get content descendants `$client->content()->descendants()`
* Page comments can also be retrieved `$client->content()->children($page, Content::CONTENT_TYPE_COMMENT)`
* The complete body is now retrieved as default

Author: Artem Stepin

README.md

@@ -20,16 +20,17 @@ $ php composer.phar require cloudplaydev/confluence-php-client
 declare(strict_types=1);
 
 use CloudPlayDev\ConfluenceClient\ConfluenceClient;
-use CloudPlayDev\ConfluenceClient\Entity\Content as ContentEntity;
+use CloudPlayDev\ConfluenceClient\Api\Content;
+use CloudPlayDev\ConfluenceClient\Entity\ContentPage;
 
 //Create the Confluence Client
 $client = new ConfluenceClient('https://url-to-conluence');
 
 //authenticate with a private access token
 $client->authenticate('NjU2OTA4NDI2MTY5OkBznOUO8YjaUF7KoOruZRXhILJ9');
 
-//Create a confluence content
-$page = new ContentEntity();
+//Create a confluence content page
+$page = new ContentPage();
 
 //Configure your page
 $page->setSpace('testSpaceKey')
@@ -49,14 +50,10 @@ $createdPage = $client->content()->findOneBy([
 $createdPage->setContent('some new content');
 $client->content()->update($createdPage);
 
+//get child content
+$childContent = $client->content()->children($createdPage, Content::CONTENT_TYPE_PAGE);
 
 
-```
-
-
-### Get your development instance
 
-Atlassian changed the way to work on Confluence/Jira, now in order to create your plugin, you have to get a [Developer Account](http://go.atlassian.com/cloud-dev) and create your own instance. All the steps to create your environment are defined on the [documentation page](https://developer.atlassian.com/static/connect/docs/latest/guides/development-setup.html).
-
-Once you have access to your own Atlassian Cloud instance and you put it in developer mode, we can continue and let the instance contact us.
+```
 

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "cloudplaydev/confluence-php-client",
   "description": "Confluence API PHP Client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "keywords": [
     "Atlassian",

src/Api/Content.php

@@ -3,43 +3,69 @@
 
 namespace CloudPlayDev\ConfluenceClient\Api;
 
-use CloudPlayDev\ConfluenceClient\Entity\Content as ContentEntity;
+use CloudPlayDev\ConfluenceClient\Entity\AbstractContent;
+use CloudPlayDev\ConfluenceClient\Entity\ContentComment;
+use CloudPlayDev\ConfluenceClient\Entity\ContentPage;
 use CloudPlayDev\ConfluenceClient\Exception\Exception;
 use CloudPlayDev\ConfluenceClient\Exception\RequestException;
 use Http\Client\Exception as HttpClientException;
 use JsonException;
 use Psr\Http\Message\ResponseInterface;
+use function assert;
 use function count;
 use function in_array;
 use function is_array;
+use function is_int;
+use function is_string;
 
+/**
+ * Class Content
+ * @package CloudPlayDev\ConfluenceClient\Api
+ */
 class Content extends AbstractApi
 {
     /**
-     * @param int|null $contentId
+     * ContentType for confluence attachments
+     */
+    public const CONTENT_TYPE_ATTACHMENT = 'attachment';
+
+    /**
+     * ContentType for confluence comments
+     */
+    public const CONTENT_TYPE_COMMENT = 'comment';
+
+    /**
+     * ContentType for confluence page content
+     */
+    public const CONTENT_TYPE_PAGE = 'page';
+
+    /**
+     * @param string|int|null ...$parameter
      * @return string
      */
-    private static function getContentUri(?int $contentId = null): string
+    private static function getContentUri(...$parameter): string
     {
         $uri = 'content';
-        if (null !== $contentId) {
-            $uri .= '/' . $contentId;
+        $parameterString = implode('/', array_filter($parameter));
+
+        if (!empty($parameterString)) {
+            $uri .= '/' . $parameterString;
         }
 
-        return $uri;
+        return $uri . '?';
     }
 
     /**
      * @param int $contentId
-     * @return ContentEntity
+     * @return AbstractContent
      * @throws Exception
      * @throws JsonException
      * @throws RequestException
      * @throws HttpClientException
      */
-    public function findOneById(int $contentId): ContentEntity
+    public function findOneById(int $contentId): AbstractContent
     {
-        $response = $this->get(self::getContentUri($contentId));
+        $response = $this->get(self::getContentUri($contentId), ['expand' => 'space,version,body.storage']);
 
         if ($response->getStatusCode() !== 200) {
             throw new RequestException($response);
@@ -49,13 +75,13 @@ public function findOneById(int $contentId): ContentEntity
     }
 
     /**
-     * @param ContentEntity $page
+     * @param AbstractContent $page
      * @return ResponseInterface
      * @throws Exception
      * @throws JsonException
      * @throws HttpClientException
      */
-    public function update(ContentEntity $page): ResponseInterface
+    public function update(AbstractContent $page): ResponseInterface
     {
         $contentId = $page->getId();
         if (null === $contentId) {
@@ -80,13 +106,13 @@ public function update(ContentEntity $page): ResponseInterface
     }
 
     /**
-     * @param ContentEntity $page
-     * @return ContentEntity
+     * @param AbstractContent $page
+     * @return AbstractContent
      * @throws Exception
      * @throws HttpClientException
      * @throws JsonException
      */
-    public function create(ContentEntity $page): ContentEntity
+    public function create(AbstractContent $page): AbstractContent
     {
         if (null !== $page->getId()) {
             throw new Exception('Only new pages can be created.');
@@ -115,10 +141,10 @@ public function create(ContentEntity $page): ContentEntity
     }
 
     /**
-     * @param ContentEntity $page
+     * @param AbstractContent $page
      * @return ResponseInterface
      */
-    public function remove(ContentEntity $page): ResponseInterface
+    public function remove(AbstractContent $page): ResponseInterface
     {
         $contentId = $page->getId();
         if (null === $contentId) {
@@ -128,43 +154,95 @@ public function remove(ContentEntity $page): ResponseInterface
     }
 
     /**
-     * @param array{title?: string, spaceKey?: string, type?: string, id?: int|string, expand?: string} $searchParameter
-     * @return ContentEntity|null
+     * @param AbstractContent $content
+     * @param string|null $contentType
+     * @return AbstractContent[]
+     * @throws HttpClientException
+     * @throws JsonException
+     */
+    public function children(AbstractContent $content, ?string $contentType = null): array
+    {
+        return $this->parseSearchResults(
+            $this->get(
+                self::getContentUri($content->getId(), 'child', $contentType),
+                ['expand' => 'space,version,body.storage']
+            ),
+        );
+    }
+
+    /**
+     * @param AbstractContent $content
+     * @param string|null $contentType
+     * @return AbstractContent[]
+     * @throws HttpClientException
+     * @throws JsonException
+     */
+    public function descendants(AbstractContent $content, ?string $contentType = null): array
+    {
+        return $this->parseSearchResults($this->get(self::getContentUri($content->getId(), 'descendant', $contentType)));
+    }
+
+    /**
+     * @param array{title?: string, spaceKey?: string, type?: string, id?: int|string} $searchParameter
+     * @return AbstractContent|null
      * @throws Exception
      * @throws JsonException
      */
-    public function findOneBy(array $searchParameter): ?ContentEntity
+    public function findOneBy(array $searchParameter): ?AbstractContent
     {
-        $allowedSearchParameter = ['title', 'spaceKey', 'type', 'id', 'expand'];
+        $allowedSearchParameter = ['title', 'spaceKey', 'type', 'id'];
         $queryParameter = array_filter($searchParameter, static function (string $searchKey) use ($allowedSearchParameter) {
             return in_array($searchKey, $allowedSearchParameter, true);
         }, ARRAY_FILTER_USE_KEY);
 
+        $queryParameter['expand'] = 'space,version,body.storage';
+
         $searchResponse = $this->get('content?', $queryParameter);
 
         if ($searchResponse->getStatusCode() !== 200) {
             throw new RequestException($searchResponse);
         }
 
-        $decodedSearchResponse = (array)json_decode($searchResponse->getBody()->getContents(), true, 512, JSON_THROW_ON_ERROR);
+        $searchResults = $this->parseSearchResults($searchResponse);
+        if (count($searchResults) > 0) {
+            return reset($searchResults);
+        }
+
+        return null;
+    }
+
+    /**
+     * @param ResponseInterface $response
+     * @return AbstractContent[]
+     * @throws JsonException
+     */
+    private function parseSearchResults(ResponseInterface $response): array
+    {
+        $decodedSearchResponse = json_decode($response->getBody()->getContents(), true, 512, JSON_THROW_ON_ERROR);
+        assert(is_array($decodedSearchResponse));
+        assert(isset($decodedSearchResponse['results'], $decodedSearchResponse['size']));
+        assert(is_array($decodedSearchResponse['results']));
+        assert(is_int($decodedSearchResponse['size']));
+
+        $results = [];
+        if ($decodedSearchResponse['size'] >= 1 && count($decodedSearchResponse['results']) >= 1) {
 
-        if (isset($decodedSearchResponse['results'], $decodedSearchResponse['size']) && is_array($decodedSearchResponse['results']) && $decodedSearchResponse['size'] >= 1 && count($decodedSearchResponse['results']) >= 1) {
-            $firstPage = (array)reset($decodedSearchResponse['results']);
-            if (isset($firstPage['id'])) {
-                return $this->findOneById((int)$firstPage['id']);
+            foreach ($decodedSearchResponse['results'] as $resultEntity) {
+                assert(is_array($resultEntity));
+                $results[] = $this->deserializeContent($resultEntity);
             }
         }
 
-        return null;
+        return $results;
     }
 
     /**
      * @param ResponseInterface $response
-     * @return ContentEntity
+     * @return AbstractContent
      * @throws Exception
      * @throws JsonException
      */
-    private function deserialize(ResponseInterface $response): ContentEntity
+    private function deserialize(ResponseInterface $response): AbstractContent
     {
         $responseData = $response->getBody()->getContents();
 
@@ -179,29 +257,42 @@ private function deserialize(ResponseInterface $response): ContentEntity
 
     /**
      * @param mixed[] $decodedData
-     * @return ContentEntity
+     * @return AbstractContent
      * @throws Exception
      */
-    private function deserializeContent(array $decodedData): ContentEntity
+    private function deserializeContent(array $decodedData): AbstractContent
     {
-        if (!isset($decodedData['id'],
+        assert(isset($decodedData['id'],
             $decodedData['type'],
             $decodedData['title'],
-            $decodedData['_links']['self'],
-            $decodedData['space']['key'],
-            $decodedData['version']['number'])
-        ) {
-            throw new Exception('Invalid content data');
+            $decodedData['_links']['self']));
+        assert(is_string($decodedData['type']));
+
+        switch ($decodedData['type']) {
+            case self::CONTENT_TYPE_PAGE:
+                $content = new ContentPage();
+                break;
+            case self::CONTENT_TYPE_COMMENT:
+                $content = new ContentComment();
+                break;
+            default:
+                throw new Exception('Invalid content type: ' . $decodedData['type']);
         }
 
-        $page = new ContentEntity();
-        $page->setId((int)$decodedData['id']);
-        $page->setType((string)$decodedData['type']);
-        $page->setTitle((string)$decodedData['title']);
-        $page->setUrl((string)$decodedData['_links']['self']);
-        $page->setSpace(str_replace('/rest/api/space/', '', (string)$decodedData['space']['key']));
-        $page->setVersion((int)$decodedData['version']['number']);
+        $content->setId((int)$decodedData['id']);
+        $content->setType($decodedData['type']);
+        $content->setTitle((string)$decodedData['title']);
+        $content->setUrl((string)$decodedData['_links']['self']);
+        if (isset($decodedData['space']['key'])) {
+            $content->setSpace((string)$decodedData['space']['key']);
+        }
+        if (isset($decodedData['version']['number'])) {
+            $content->setVersion((int)$decodedData['version']['number']);
+        }
+        if(isset($decodedData['body']['storage']['value'])) {
+            $content->setContent($decodedData['body']['storage']['value']);
+        }
 
-        return $page;
+        return $content;
     }
 }