Add New Method for Returning Board List With Offset/Paginated Results (…

…#535)

* Create BoardResult.php

- Create a new class to hold the entire result data of the response returned from the "/rest/agile/1.0/board" endpoint

- The approach is very similar to how the existing IssueService->search() function works already

* Update BoardService.php

- Instead of updating the existing getAllBoards() method and create a breaking change, I introduced a new method getBoards()

- This method calls to the same "/rest/agile/1.0/board" endpoint as getAllBoards() but it maps the value into the newly created BoardResult class rather than ArrayObject.

- This allows the developer to determine if there are more results past the initial 50 on the first page, and get additional pages if necessary

* Update BoardTest.php

- Created a new test method which performs the same test as the get_all_boards() test but using the updated result object instead

* Update README.md

Add information about how to use the new getBoards() method to retrieve the entire list of board results

* Add periods to end of comments

Added these in order to pass StyleCI PR checks

* Rename BoardResult to more generic PaginatedResult

I realized other methods in BoardService also did not have proper pagination built in.  We will reuse this class in a more generic way for other methods such as getSprintsForBoard()

* Update BoardService.php

- Update our new getBoards() method to return PaginatedResult instead of BoardResult
- Add new method getSprintsForBoard() which has support for pagination and uses PaginatedResult

README.md

@@ -2470,6 +2470,43 @@ try {
 }
 
 ```
+
+#### Get boards
+[See Jira API reference](https://developer.atlassian.com/cloud/jira/software/rest/#api-rest-agile-1-0-board-get)
+
+```php
+<?php
+require 'vendor/autoload.php';
+
+use JiraRestApi\Board\BoardService;
+
+try {
+  $results = [];
+  $startAt = 0;
+  $maxResults = 50; // maximum allowed for board queries
+
+  do {
+      $response = $this->boardService->getBoards([
+        'startAt' => $startAt,
+        'maxResults' => $maxResults
+      ]);
+
+      $results = [...$results, ...$response->getBoards()];
+
+      $startAt += $maxResults;
+
+  } while($startAt < $response->total);
+
+  var_dump($results);
+
+} catch (JiraRestApi\JiraException $e) {
+    print('Error Occured! ' . $e->getMessage());
+}
+
+```
+
+
+
 #### Get board info
 [See Jira API reference](https://developer.atlassian.com/cloud/jira/software/rest/#api-rest-agile-1-0-board-boardId-get)
 

src/Board/BoardService.php

@@ -46,6 +46,29 @@ public function getBoardList($paramArray = []): ?\ArrayObject
         }
     }
 
+    /**
+     * Get list of boards with paginated results.
+     *
+     * @param array $paramArray
+     *
+     * @return PaginatedResult|null array of Board class
+     *@throws \JiraRestApi\JiraException
+     *
+     */
+    public function getBoards($paramArray = []): ?PaginatedResult
+    {
+        $json = $this->exec($this->uri.$this->toHttpQueryParameter($paramArray), null);
+        try {
+            return $this->json_mapper->map(
+                json_decode($json, false, 512, $this->getJsonOptions()),
+                new PaginatedResult()
+            );
+        } catch (\JsonException $exception) {
+            $this->log->error("Response cannot be decoded from json\nException: {$exception->getMessage()}");
+            return null;
+        }
+    }
+
     public function getBoard($id, $paramArray = []): ?Board
     {
         $json = $this->exec($this->uri.'/'.$id.$this->toHttpQueryParameter($paramArray), null);
@@ -122,6 +145,30 @@ public function getBoardSprints($boardId, $paramArray = []): ?\ArrayObject
         }
     }
 
+    /**
+     * Get list of boards with paginated results.
+     *
+     * @param array $paramArray
+     *
+     * @throws \JiraRestApi\JiraException
+     *
+     * @return PaginatedResult|null array of Board class
+     */
+    public function getSprintsForBoard($boardId, $paramArray = []): ?PaginatedResult
+    {
+        $json = $this->exec($this->uri.'/'.$boardId.'/sprint'.$this->toHttpQueryParameter($paramArray), null);
+
+        try {
+            return $this->json_mapper->map(
+                json_decode($json, false, 512, $this->getJsonOptions()),
+                new PaginatedResult()
+            );
+        } catch (\JsonException $exception) {
+            $this->log->error("Response cannot be decoded from json\nException: {$exception->getMessage()}");
+            return null;
+        }
+    }
+
     /**
      * @return \ArrayObject|Epic[]|null
      */

src/Board/PaginatedResult.php

@@ -0,0 +1,129 @@
+<?php
+
+namespace JiraRestApi\Board;
+
+/**
+ * Paginated Result object for BoardService
+ */
+class PaginatedResult
+{
+    /**
+     * @var string
+     */
+    public $expand;
+
+    /**
+     * @var int
+     */
+    public $startAt;
+
+    /**
+     * @var int
+     */
+    public $maxResults;
+
+    /**
+     * @var int
+     */
+    public $total;
+
+    /**
+     * @var array
+     */
+    public $values;
+
+    /**
+     * @var bool
+     */
+    public $isLast;
+
+    /**
+     * @return int
+     */
+    public function getStartAt()
+    {
+        return $this->startAt;
+    }
+
+    /**
+     * @param int $startAt
+     */
+    public function setStartAt($startAt)
+    {
+        $this->startAt = $startAt;
+    }
+
+    /**
+     * @return int
+     */
+    public function getMaxResults()
+    {
+        return $this->maxResults;
+    }
+
+    /**
+     * @param int $maxResults
+     */
+    public function setMaxResults($maxResults)
+    {
+        $this->maxResults = $maxResults;
+    }
+
+    /**
+     * @return int
+     */
+    public function getTotal()
+    {
+        return $this->total;
+    }
+
+    /**
+     * @param int $total
+     */
+    public function setTotal($total)
+    {
+        $this->total = $total;
+    }
+
+    /**
+     * @return array
+     */
+    public function getValues()
+    {
+        return $this->values;
+    }
+
+    /**
+     * @param array $values
+     */
+    public function setValues($values)
+    {
+        $this->values = $values;
+    }
+
+    /**
+     * @param int $index
+     *
+     * @return mixed
+     */
+    public function getValue($index)
+    {
+        return $this->values[$index];
+    }
+
+    /**
+     * @return string
+     */
+    public function getExpand()
+    {
+        return $this->expand;
+    }
+
+    /**
+     * @param string $expand
+     */
+    public function setExpand($expand)
+    {
+        $this->expand = $expand;
+    }
+}

tests/BoardTest.php

@@ -41,6 +41,31 @@ public function get_all_boards() : string
         return $last_board_id;
     }
 
+    /**
+     * @test
+     *
+     * Test we can obtain the paginated board list.
+     */
+    public function get_boards() : string
+    {
+        $board_service = new BoardService();
+
+        $board_list = $board_service->getBoards();
+        $this->assertInstanceOf(BoardResult::class, $board_list, 'We receive a board list.');
+
+        $last_board_id = null;
+        foreach ($board_list->getBoards() as $board) {
+            $this->assertInstanceOf(Board::class, $board, 'Each element of the list is a Board instance.');
+            $this->assertNotNull($board->self, 'self must not null');
+            $this->assertNotNull($board->name, 'name must not null');
+            $this->assertNotNull($board->type, 'type must not null');
+
+            $last_board_id = $board->id;
+        }
+
+        return $last_board_id;
+    }
+
     /**
      * @test
      *