Skip to content

Commit 087718a

Browse files
nickpoulosnickpoulos
authored
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
1 parent e01f543 commit 087718a

File tree

4 files changed

+238
-0
lines changed

4 files changed

+238
-0
lines changed

‎README.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2470,6 +2470,43 @@ try {
24702470
}
24712471

24722472
```
2473+
2474+
#### Get boards
2475+
[See Jira API reference](https://developer.atlassian.com/cloud/jira/software/rest/#api-rest-agile-1-0-board-get)
2476+
2477+
```php
2478+
<?php
2479+
require 'vendor/autoload.php';
2480+
2481+
use JiraRestApi\Board\BoardService;
2482+
2483+
try {
2484+
$results = [];
2485+
$startAt = 0;
2486+
$maxResults = 50; // maximum allowed for board queries
2487+
2488+
do {
2489+
$response = $this->boardService->getBoards([
2490+
'startAt' => $startAt,
2491+
'maxResults' => $maxResults
2492+
]);
2493+
2494+
$results = [...$results, ...$response->getBoards()];
2495+
2496+
$startAt += $maxResults;
2497+
2498+
} while($startAt < $response->total);
2499+
2500+
var_dump($results);
2501+
2502+
} catch (JiraRestApi\JiraException $e) {
2503+
print('Error Occured! ' . $e->getMessage());
2504+
}
2505+
2506+
```
2507+
2508+
2509+
24732510
#### Get board info
24742511
[See Jira API reference](https://developer.atlassian.com/cloud/jira/software/rest/#api-rest-agile-1-0-board-boardId-get)
24752512

‎src/Board/BoardService.php

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,29 @@ public function getBoardList($paramArray = []): ?\ArrayObject
4646
}
4747
}
4848

49+
/**
50+
* Get list of boards with paginated results.
51+
*
52+
* @param array $paramArray
53+
*
54+
* @return PaginatedResult|null array of Board class
55+
*@throws \JiraRestApi\JiraException
56+
*
57+
*/
58+
public function getBoards($paramArray = []): ?PaginatedResult
59+
{
60+
$json = $this->exec($this->uri.$this->toHttpQueryParameter($paramArray), null);
61+
try {
62+
return $this->json_mapper->map(
63+
json_decode($json, false, 512, $this->getJsonOptions()),
64+
new PaginatedResult()
65+
);
66+
} catch (\JsonException $exception) {
67+
$this->log->error("Response cannot be decoded from json\nException: {$exception->getMessage()}");
68+
return null;
69+
}
70+
}
71+
4972
public function getBoard($id, $paramArray = []): ?Board
5073
{
5174
$json = $this->exec($this->uri.'/'.$id.$this->toHttpQueryParameter($paramArray), null);
@@ -122,6 +145,30 @@ public function getBoardSprints($boardId, $paramArray = []): ?\ArrayObject
122145
}
123146
}
124147

148+
/**
149+
* Get list of boards with paginated results.
150+
*
151+
* @param array $paramArray
152+
*
153+
* @throws \JiraRestApi\JiraException
154+
*
155+
* @return PaginatedResult|null array of Board class
156+
*/
157+
public function getSprintsForBoard($boardId, $paramArray = []): ?PaginatedResult
158+
{
159+
$json = $this->exec($this->uri.'/'.$boardId.'/sprint'.$this->toHttpQueryParameter($paramArray), null);
160+
161+
try {
162+
return $this->json_mapper->map(
163+
json_decode($json, false, 512, $this->getJsonOptions()),
164+
new PaginatedResult()
165+
);
166+
} catch (\JsonException $exception) {
167+
$this->log->error("Response cannot be decoded from json\nException: {$exception->getMessage()}");
168+
return null;
169+
}
170+
}
171+
125172
/**
126173
* @return \ArrayObject|Epic[]|null
127174
*/

‎src/Board/PaginatedResult.php

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
<?php
2+
3+
namespace JiraRestApi\Board;
4+
5+
/**
6+
* Paginated Result object for BoardService
7+
*/
8+
class PaginatedResult
9+
{
10+
/**
11+
* @var string
12+
*/
13+
public $expand;
14+
15+
/**
16+
* @var int
17+
*/
18+
public $startAt;
19+
20+
/**
21+
* @var int
22+
*/
23+
public $maxResults;
24+
25+
/**
26+
* @var int
27+
*/
28+
public $total;
29+
30+
/**
31+
* @var array
32+
*/
33+
public $values;
34+
35+
/**
36+
* @var bool
37+
*/
38+
public $isLast;
39+
40+
/**
41+
* @return int
42+
*/
43+
public function getStartAt()
44+
{
45+
return $this->startAt;
46+
}
47+
48+
/**
49+
* @param int $startAt
50+
*/
51+
public function setStartAt($startAt)
52+
{
53+
$this->startAt = $startAt;
54+
}
55+
56+
/**
57+
* @return int
58+
*/
59+
public function getMaxResults()
60+
{
61+
return $this->maxResults;
62+
}
63+
64+
/**
65+
* @param int $maxResults
66+
*/
67+
public function setMaxResults($maxResults)
68+
{
69+
$this->maxResults = $maxResults;
70+
}
71+
72+
/**
73+
* @return int
74+
*/
75+
public function getTotal()
76+
{
77+
return $this->total;
78+
}
79+
80+
/**
81+
* @param int $total
82+
*/
83+
public function setTotal($total)
84+
{
85+
$this->total = $total;
86+
}
87+
88+
/**
89+
* @return array
90+
*/
91+
public function getValues()
92+
{
93+
return $this->values;
94+
}
95+
96+
/**
97+
* @param array $values
98+
*/
99+
public function setValues($values)
100+
{
101+
$this->values = $values;
102+
}
103+
104+
/**
105+
* @param int $index
106+
*
107+
* @return mixed
108+
*/
109+
public function getValue($index)
110+
{
111+
return $this->values[$index];
112+
}
113+
114+
/**
115+
* @return string
116+
*/
117+
public function getExpand()
118+
{
119+
return $this->expand;
120+
}
121+
122+
/**
123+
* @param string $expand
124+
*/
125+
public function setExpand($expand)
126+
{
127+
$this->expand = $expand;
128+
}
129+
}

‎tests/BoardTest.php

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,31 @@ public function get_all_boards() : string
4141
return $last_board_id;
4242
}
4343

44+
/**
45+
* @test
46+
*
47+
* Test we can obtain the paginated board list.
48+
*/
49+
public function get_boards() : string
50+
{
51+
$board_service = new BoardService();
52+
53+
$board_list = $board_service->getBoards();
54+
$this->assertInstanceOf(BoardResult::class, $board_list, 'We receive a board list.');
55+
56+
$last_board_id = null;
57+
foreach ($board_list->getBoards() as $board) {
58+
$this->assertInstanceOf(Board::class, $board, 'Each element of the list is a Board instance.');
59+
$this->assertNotNull($board->self, 'self must not null');
60+
$this->assertNotNull($board->name, 'name must not null');
61+
$this->assertNotNull($board->type, 'type must not null');
62+
63+
$last_board_id = $board->id;
64+
}
65+
66+
return $last_board_id;
67+
}
68+
4469
/**
4570
* @test
4671
*

0 commit comments

Comments
 (0)