Skip to content

Commit 5765b64

Browse files
lodelode
committed
add strict type to profile
1 parent 20d2784 commit 5765b64

File tree

1 file changed

+50
-120
lines changed

1 file changed

+50
-120
lines changed

‎src/profiles/CursorPaginationProfile.php‎

Lines changed: 50 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -56,54 +56,47 @@ class CursorPaginationProfile implements ProfileInterface {
5656
/**
5757
* set links to paginate the data using cursors of the paginated data
5858
*
59-
* @param PaginableInterface $paginable a CollectionDocument or RelationshipObject
60-
* @param string $baseOrCurrentUrl
61-
* @param string $firstCursor
62-
* @param string $lastCursor
59+
* @param PaginableInterface $paginable a CollectionDocument or RelationshipObject
6360
*/
64-
public function setLinks(PaginableInterface $paginable, $baseOrCurrentUrl, $firstCursor, $lastCursor) {
61+
public function setLinks(
62+
PaginableInterface $paginable,
63+
string $baseOrCurrentUrl,
64+
string $firstCursor,
65+
string $lastCursor,
66+
): void {
6567
$previousLinkObject = new LinkObject($this->generatePreviousLink($baseOrCurrentUrl, $firstCursor));
6668
$nextLinkObject = new LinkObject($this->generateNextLink($baseOrCurrentUrl, $lastCursor));
6769

6870
$this->setPaginationLinkObjects($paginable, $previousLinkObject, $nextLinkObject);
6971
}
7072

7173
/**
72-
* @param PaginableInterface $paginable a CollectionDocument or RelationshipObject
73-
* @param string $baseOrCurrentUrl
74-
* @param string $lastCursor
74+
* @param PaginableInterface $paginable a CollectionDocument or RelationshipObject
7575
*/
76-
public function setLinksFirstPage(PaginableInterface $paginable, $baseOrCurrentUrl, $lastCursor) {
76+
public function setLinksFirstPage(PaginableInterface $paginable, string $baseOrCurrentUrl, string $lastCursor): void {
7777
$this->setPaginationLinkObjectsWithoutPrevious($paginable, $baseOrCurrentUrl, $lastCursor);
7878
}
7979

8080
/**
81-
* @param PaginableInterface $paginable a CollectionDocument or RelationshipObject
82-
* @param string $baseOrCurrentUrl
83-
* @param string $firstCursor
81+
* @param PaginableInterface $paginable a CollectionDocument or RelationshipObject
8482
*/
85-
public function setLinksLastPage(PaginableInterface $paginable, $baseOrCurrentUrl, $firstCursor) {
83+
public function setLinksLastPage(PaginableInterface $paginable, string $baseOrCurrentUrl, string $firstCursor): void {
8684
$this->setPaginationLinkObjectsWithoutNext($paginable, $baseOrCurrentUrl, $firstCursor);
8785
}
8886

8987
/**
9088
* set the cursor of a specific resource to allow pagination after or before this resource
91-
*
92-
* @param ResourceInterface $resource
93-
* @param string $cursor
9489
*/
95-
public function setCursor(ResourceInterface $resource, $cursor) {
90+
public function setCursor(ResourceInterface $resource, string $cursor): void {
9691
$this->setItemMeta($resource, $cursor);
9792
}
9893

9994
/**
10095
* set count(s) to tell about the (estimated) total size
10196
*
102-
* @param PaginableInterface $paginable a CollectionDocument or RelationshipObject
103-
* @param int $exactTotal optional
104-
* @param int $bestGuessTotal optional
97+
* @param PaginableInterface $paginable a CollectionDocument or RelationshipObject
10598
*/
106-
public function setCount(PaginableInterface $paginable, $exactTotal=null, $bestGuessTotal=null) {
99+
public function setCount(PaginableInterface $paginable, ?int $exactTotal=null, ?int $bestGuessTotal=null) {
107100
$this->setPaginationMeta($paginable, $exactTotal, $bestGuessTotal);
108101
}
109102

@@ -113,21 +106,13 @@ public function setCount(PaginableInterface $paginable, $exactTotal=null, $bestG
113106

114107
/**
115108
* helper to get generate a correct page[before] link, use to apply manually
116-
*
117-
* @param string $baseOrCurrentUrl
118-
* @param string $beforeCursor
119-
* @return string
120109
*/
121-
public function generatePreviousLink($baseOrCurrentUrl, $beforeCursor) {
110+
public function generatePreviousLink(string $baseOrCurrentUrl, string $beforeCursor): string {
122111
return $this->setQueryParameter($baseOrCurrentUrl, 'page[before]', $beforeCursor);
123112
}
124113

125114
/**
126115
* helper to get generate a correct page[after] link, use to apply manually
127-
*
128-
* @param string $baseOrCurrentUrl
129-
* @param string $afterCursor
130-
* @return string
131116
*/
132117
public function generateNextLink($baseOrCurrentUrl, $afterCursor) {
133118
return $this->setQueryParameter($baseOrCurrentUrl, 'page[after]', $afterCursor);
@@ -142,42 +127,25 @@ public function generateNextLink($baseOrCurrentUrl, $afterCursor) {
142127
* - /data/0/relationships/foo/links/prev & /data/0/relationships/foo/links/next
143128
*
144129
* @see https://jsonapi.org/profiles/ethanresnick/cursor-pagination/#terms-pagination-links
145-
*
146-
* @param PaginableInterface&HasLinksInterface $paginable
147-
* @param LinkObject $previousLinkObject
148-
* @param LinkObject $nextLinkObject
149130
*/
150-
public function setPaginationLinkObjects(PaginableInterface $paginable, LinkObject $previousLinkObject, LinkObject $nextLinkObject) {
151-
if ($paginable instanceof HasLinksInterface === false) {
152-
throw new InputException('unsupported paginable to set pagination links on');
153-
}
154-
131+
public function setPaginationLinkObjects(
132+
PaginableInterface & HasLinksInterface $paginable,
133+
LinkObject $previousLinkObject,
134+
LinkObject $nextLinkObject,
135+
): void {
155136
$paginable->addLinkObject('prev', $previousLinkObject);
156137
$paginable->addLinkObject('next', $nextLinkObject);
157138
}
158139

159-
/**
160-
* @param PaginableInterface $paginable
161-
* @param string $baseOrCurrentUrl
162-
* @param string $firstCursor
163-
*/
164-
public function setPaginationLinkObjectsWithoutNext(PaginableInterface $paginable, $baseOrCurrentUrl, $firstCursor) {
140+
public function setPaginationLinkObjectsWithoutNext(PaginableInterface $paginable, string $baseOrCurrentUrl, string $firstCursor): void {
165141
$this->setPaginationLinkObjects($paginable, new LinkObject($this->generatePreviousLink($baseOrCurrentUrl, $firstCursor)), new LinkObject());
166142
}
167143

168-
/**
169-
* @param PaginableInterface $paginable
170-
* @param string $baseOrCurrentUrl
171-
* @param string $lastCursor
172-
*/
173-
public function setPaginationLinkObjectsWithoutPrevious(PaginableInterface $paginable, $baseOrCurrentUrl, $lastCursor) {
144+
public function setPaginationLinkObjectsWithoutPrevious(PaginableInterface $paginable, string $baseOrCurrentUrl, string $lastCursor): void {
174145
$this->setPaginationLinkObjects($paginable, new LinkObject(), new LinkObject($this->generateNextLink($baseOrCurrentUrl, $lastCursor)));
175146
}
176147

177-
/**
178-
* @param PaginableInterface $paginable
179-
*/
180-
public function setPaginationLinkObjectsExplicitlyEmpty(PaginableInterface $paginable) {
148+
public function setPaginationLinkObjectsExplicitlyEmpty(PaginableInterface $paginable): void {
181149
$this->setPaginationLinkObjects($paginable, new LinkObject(), new LinkObject());
182150
}
183151

@@ -190,15 +158,8 @@ public function setPaginationLinkObjectsExplicitlyEmpty(PaginableInterface $pagi
190158
* - /data/0/relationships/foo/meta/page
191159
*
192160
* @see https://jsonapi.org/profiles/ethanresnick/cursor-pagination/#terms-pagination-item-metadata
193-
*
194-
* @param ResourceInterface&HasMetaInterface $resource
195-
* @param string $cursor
196161
*/
197-
public function setItemMeta(ResourceInterface $resource, $cursor) {
198-
if ($resource instanceof HasMetaInterface === false) {
199-
throw new InputException('resource doesn\'t support meta');
200-
}
201-
162+
public function setItemMeta(ResourceInterface & HasMetaInterface $resource, string $cursor): void {
202163
$metadata = [
203164
'cursor' => $cursor,
204165
];
@@ -221,16 +182,14 @@ public function setItemMeta(ResourceInterface $resource, $cursor) {
221182
*
222183
* @see https://jsonapi.org/profiles/ethanresnick/cursor-pagination/#terms-pagination-metadata
223184
*
224-
* @param PaginableInterface&HasMetaInterface $paginable
225-
* @param int $exactTotal optional
226-
* @param int $bestGuessTotal optional
227-
* @param boolean $rangeIsTruncated optional, if both after and before are supplied but the items exceed requested or max size
185+
* @param boolean $rangeIsTruncated, if both after and before are supplied but the items exceed requested or max size
228186
*/
229-
public function setPaginationMeta(PaginableInterface $paginable, $exactTotal=null, $bestGuessTotal=null, $rangeIsTruncated=null) {
230-
if ($paginable instanceof HasMetaInterface === false) {
231-
throw new InputException('paginable doesn\'t support meta');
232-
}
233-
187+
public function setPaginationMeta(
188+
PaginableInterface & HasMetaInterface $paginable,
189+
?int $exactTotal=null,
190+
?int $bestGuessTotal=null,
191+
?bool $rangeIsTruncated=null,
192+
): void {
234193
$metadata = [];
235194

236195
if ($exactTotal !== null) {
@@ -252,18 +211,9 @@ public function setPaginationMeta(PaginableInterface $paginable, $exactTotal=nul
252211
* get an ErrorObject for when the requested sorting cannot efficiently be paginated
253212
*
254213
* ends up at:
255-
* - /errors/0/code
256-
* - /errors/0/status
257-
* - /errors/0/source/parameter
258-
* - /errors/0/links/type/0
259-
* - /errors/0/title optional
260-
* - /errors/0/detail optional
261-
*
262-
* @param string $genericTitle optional
263-
* @param string $specificDetails optional
264-
* @return ErrorObject
214+
* - /errors/0/*
265215
*/
266-
public function getUnsupportedSortErrorObject($genericTitle=null, $specificDetails=null) {
216+
public function getUnsupportedSortErrorObject(?string $genericTitle=null, ?string $specificDetails=null): ErrorObject {
267217
$errorObject = new ErrorObject('Unsupported sort');
268218
$errorObject->setTypeLink('https://jsonapi.org/profiles/ethanresnick/cursor-pagination/unsupported-sort');
269219
$errorObject->blameQueryParameter('sort');
@@ -280,20 +230,12 @@ public function getUnsupportedSortErrorObject($genericTitle=null, $specificDetai
280230
* get an ErrorObject for when the requested page size exceeds the server-defined max page size
281231
*
282232
* ends up at:
283-
* - /errors/0/code
284-
* - /errors/0/status
285-
* - /errors/0/source/parameter
286-
* - /errors/0/links/type/0
287-
* - /errors/0/meta/page/maxSize
288-
* - /errors/0/title optional
289-
* - /errors/0/detail optional
233+
* - /errors/0/*
290234
*
291-
* @param int $maxSize
292-
* @param string $genericTitle optional, e.g. 'Page size requested is too large.'
293-
* @param string $specificDetails optional, e.g. 'You requested a size of 200, but 100 is the maximum.'
294-
* @return ErrorObject
235+
* @param string $genericTitle e.g. 'Page size requested is too large.'
236+
* @param string $specificDetails e.g. 'You requested a size of 200, but 100 is the maximum.'
295237
*/
296-
public function getMaxPageSizeExceededErrorObject($maxSize, $genericTitle=null, $specificDetails=null) {
238+
public function getMaxPageSizeExceededErrorObject(int $maxSize, ?string $genericTitle=null, ?string $specificDetails=null): ErrorObject {
297239
$errorObject = new ErrorObject('Max page size exceeded');
298240
$errorObject->setTypeLink('https://jsonapi.org/profiles/ethanresnick/cursor-pagination/max-size-exceeded');
299241
$errorObject->blameQueryParameter('page[size]');
@@ -311,20 +253,18 @@ public function getMaxPageSizeExceededErrorObject($maxSize, $genericTitle=null,
311253
* get an ErrorObject for when the requested page size is not a positive integer, or when the requested page after/before is not a valid cursor
312254
*
313255
* ends up at:
314-
* - /errors/0/code
315-
* - /errors/0/status
316-
* - /errors/0/source/parameter
317-
* - /errors/0/links/type/0 optional
318-
* - /errors/0/title optional
319-
* - /errors/0/detail optional
256+
* - /errors/0/*
320257
*
321-
* @param int $queryParameter e.g. 'sort' or 'page[size]'
322-
* @param string $typeLink optional
323-
* @param string $genericTitle optional, e.g. 'Invalid Parameter.'
324-
* @param string $specificDetails optional, e.g. 'page[size] must be a positive integer; got 0'
325-
* @return ErrorObject
258+
* @param string $queryParameter e.g. 'sort' or 'page[size]'
259+
* @param string $genericTitle e.g. 'Invalid Parameter.'
260+
* @param string $specificDetails e.g. 'page[size] must be a positive integer; got 0'
326261
*/
327-
public function getInvalidParameterValueErrorObject($queryParameter, $typeLink=null, $genericTitle=null, $specificDetails=null) {
262+
public function getInvalidParameterValueErrorObject(
263+
string $queryParameter,
264+
?string $typeLink=null,
265+
?string $genericTitle=null,
266+
?string $specificDetails=null,
267+
): ErrorObject {
328268
$errorObject = new ErrorObject('Invalid parameter value');
329269
$errorObject->blameQueryParameter($queryParameter);
330270
$errorObject->setHttpStatusCode(400);
@@ -344,15 +284,9 @@ public function getInvalidParameterValueErrorObject($queryParameter, $typeLink=n
344284
* get an ErrorObject for when range pagination requests (when both 'page[after]' and 'page[before]' are requested) are not supported
345285
*
346286
* ends up at:
347-
* - /errors/0/code
348-
* - /errors/0/status
349-
* - /errors/0/links/type/0
350-
*
351-
* @param string $genericTitle optional
352-
* @param string $specificDetails optional
353-
* @return ErrorObject
287+
* - /errors/0/*
354288
*/
355-
public function getRangePaginationNotSupportedErrorObject($genericTitle=null, $specificDetails=null) {
289+
public function getRangePaginationNotSupportedErrorObject(?string $genericTitle=null, ?string $specificDetails=null): ErrorObject {
356290
$errorObject = new ErrorObject('Range pagination not supported');
357291
$errorObject->setTypeLink('https://jsonapi.org/profiles/ethanresnick/cursor-pagination/range-pagination-not-supported');
358292
$errorObject->setHttpStatusCode(400);
@@ -370,12 +304,8 @@ public function getRangePaginationNotSupportedErrorObject($genericTitle=null, $s
370304

371305
/**
372306
* add or adjust a key in the query string of a url
373-
*
374-
* @param string $url
375-
* @param string $key
376-
* @param string $value
377307
*/
378-
private function setQueryParameter($url, $key, $value) {
308+
private function setQueryParameter(string $url, string $key, string $value): string {
379309
$originalQuery = parse_url($url, PHP_URL_QUERY);
380310
$decodedQuery = urldecode($originalQuery);
381311
$originalIsEncoded = ($decodedQuery !== $originalQuery);

0 commit comments

Comments
 (0)