Skip to content

Commit 21c3a34

Browse files
xificurkxificurk
committed
Improve type annotations
1 parent cf89a90 commit 21c3a34

File tree

8 files changed

+56
-14
lines changed

8 files changed

+56
-14
lines changed

‎src/Utils/ArrayHash.php

+2
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515
/**
1616
* Provides objects to work as array.
1717
* @template T
18+
* @implements \IteratorAggregate<array-key, T>
19+
* @implements \ArrayAccess<array-key, T>
1820
*/
1921
class ArrayHash extends \stdClass implements \ArrayAccess, \Countable, \IteratorAggregate
2022
{

‎src/Utils/ArrayList.php

+3-1
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515
/**
1616
* Provides the base class for a generic list (items can be accessed by index).
1717
* @template T
18+
* @implements \IteratorAggregate<int, T>
19+
* @implements \ArrayAccess<int, T>
1820
*/
1921
class ArrayList implements \ArrayAccess, \Countable, \IteratorAggregate
2022
{
@@ -25,7 +27,7 @@ class ArrayList implements \ArrayAccess, \Countable, \IteratorAggregate
2527

2628
/**
2729
* Transforms array to ArrayList.
28-
* @param array<T> $array
30+
* @param list<T> $array
2931
*/
3032
public static function from(array $array): static
3133
{

‎src/Utils/Arrays.php

+1
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,7 @@ public static function flatten(array $array, bool $preserveKeys = false): array
225225

226226
/**
227227
* Checks if the array is indexed in ascending order of numeric keys from zero, a.k.a list.
228+
* @return ($value is list ? true : false)
228229
*/
229230
public static function isList(mixed $value): bool
230231
{

‎src/Utils/Image.php

+20-5
Original file line numberDiff line numberDiff line change
@@ -90,8 +90,8 @@
9090
* @method void stringUp($font, $x, $y, string $s, $col)
9191
* @method void trueColorToPalette(bool $dither, $ncolors)
9292
* @method array ttfText($size, $angle, $x, $y, $color, string $fontfile, string $text)
93-
* @property-read int $width
94-
* @property-read int $height
93+
* @property-read positive-int $width
94+
* @property-read positive-int $height
9595
* @property-read \GdImage $imageResource
9696
*/
9797
class Image
@@ -220,6 +220,8 @@ private static function invokeSafe(string $func, string $arg, string $message, s
220220

221221
/**
222222
* Creates a new true color image of the given dimensions. The default color is black.
223+
* @param positive-int $width
224+
* @param positive-int $height
223225
* @throws Nette\NotSupportedException if gd extension is not loaded
224226
*/
225227
public static function fromBlank(int $width, int $height, ?array $color = null): static
@@ -247,6 +249,7 @@ public static function fromBlank(int $width, int $height, ?array $color = null):
247249

248250
/**
249251
* Returns the type of image from file.
252+
* @return self::JPEG|self::PNG|self::GIF|self::WEBP|self::AVIF|self::BMP|null
250253
*/
251254
public static function detectTypeFromFile(string $file, &$width = null, &$height = null): ?int
252255
{
@@ -257,6 +260,7 @@ public static function detectTypeFromFile(string $file, &$width = null, &$height
257260

258261
/**
259262
* Returns the type of image from string.
263+
* @return self::JPEG|self::PNG|self::GIF|self::WEBP|self::AVIF|self::BMP|null
260264
*/
261265
public static function detectTypeFromString(string $s, &$width = null, &$height = null): ?int
262266
{
@@ -267,6 +271,8 @@ public static function detectTypeFromString(string $s, &$width = null, &$height
267271

268272
/**
269273
* Returns the file extension for the given `Image::XXX` constant.
274+
* @param self::JPEG|self::PNG|self::GIF|self::WEBP|self::AVIF|self::BMP $type
275+
* @return value-of<self::Formats>
270276
*/
271277
public static function typeToExtension(int $type): string
272278
{
@@ -280,6 +286,8 @@ public static function typeToExtension(int $type): string
280286

281287
/**
282288
* Returns the `Image::XXX` constant for given file extension.
289+
* @param value-of<self::Formats>|'jpg' $extension
290+
* @return self::JPEG|self::PNG|self::GIF|self::WEBP|self::AVIF|self::BMP
283291
*/
284292
public static function extensionToType(string $extension): int
285293
{
@@ -295,6 +303,7 @@ public static function extensionToType(string $extension): int
295303

296304
/**
297305
* Returns the mime type for the given `Image::XXX` constant.
306+
* @param self::JPEG|self::PNG|self::GIF|self::WEBP|self::AVIF|self::BMP $type
298307
*/
299308
public static function typeToMimeType(int $type): string
300309
{
@@ -314,6 +323,7 @@ public function __construct(\GdImage $image)
314323

315324
/**
316325
* Returns image width.
326+
* @return positive-int
317327
*/
318328
public function getWidth(): int
319329
{
@@ -323,6 +333,7 @@ public function getWidth(): int
323333

324334
/**
325335
* Returns image height.
336+
* @return positive-int
326337
*/
327338
public function getHeight(): int
328339
{
@@ -351,7 +362,7 @@ public function getImageResource(): \GdImage
351362

352363
/**
353364
* Scales an image. Width and height accept pixels or percent.
354-
* @param self::OrSmaller|self::OrBigger|self::Stretch|self::Cover|self::ShrinkOnly $mode
365+
* @param int-mask-of<self::OrSmaller|self::OrBigger|self::Stretch|self::Cover|self::ShrinkOnly> $mode
355366
*/
356367
public function resize(int|string|null $width, int|string|null $height, int $mode = self::OrSmaller): static
357368
{
@@ -388,7 +399,7 @@ public function resize(int|string|null $width, int|string|null $height, int $mod
388399

389400
/**
390401
* Calculates dimensions of resized image. Width and height accept pixels or percent.
391-
* @param self::OrSmaller|self::OrBigger|self::Stretch|self::Cover|self::ShrinkOnly $mode
402+
* @param int-mask-of<self::OrSmaller|self::OrBigger|self::Stretch|self::Cover|self::ShrinkOnly> $mode
392403
*/
393404
public static function calculateSize(
394405
int $srcWidth,
@@ -534,7 +545,7 @@ public function sharpen(): static
534545

535546
/**
536547
* Puts another image into this image. Left and top accepts pixels or percent.
537-
* @param int $opacity 0..100
548+
* @param int<0, 100> $opacity 0..100
538549
*/
539550
public function place(self $image, int|string $left = 0, int|string $top = 0, int $opacity = 100): static
540551
{
@@ -596,6 +607,7 @@ public function place(self $image, int|string $left = 0, int|string $top = 0, in
596607

597608
/**
598609
* Saves image to the file. Quality is in the range 0..100 for JPEG (default 85), WEBP (default 80) and AVIF (default 30) and 0..9 for PNG (default 9).
610+
* @param self::JPEG|self::PNG|self::GIF|self::WEBP|self::AVIF|self::BMP|null $type
599611
* @throws ImageException
600612
*/
601613
public function save(string $file, ?int $quality = null, ?int $type = null): void
@@ -607,6 +619,7 @@ public function save(string $file, ?int $quality = null, ?int $type = null): voi
607619

608620
/**
609621
* Outputs image to string. Quality is in the range 0..100 for JPEG (default 85), WEBP (default 80) and AVIF (default 30) and 0..9 for PNG (default 9).
622+
* @param self::JPEG|self::PNG|self::GIF|self::WEBP|self::AVIF|self::BMP $type
610623
*/
611624
public function toString(int $type = self::JPEG, ?int $quality = null): string
612625
{
@@ -627,6 +640,7 @@ public function __toString(): string
627640

628641
/**
629642
* Outputs image to browser. Quality is in the range 0..100 for JPEG (default 85), WEBP (default 80) and AVIF (default 30) and 0..9 for PNG (default 9).
643+
* @param self::JPEG|self::PNG|self::GIF|self::WEBP|self::AVIF|self::BMP $type
630644
* @throws ImageException
631645
*/
632646
public function send(int $type = self::JPEG, ?int $quality = null): void
@@ -639,6 +653,7 @@ public function send(int $type = self::JPEG, ?int $quality = null): void
639653
/**
640654
* Outputs image to browser or file.
641655
* @throws ImageException
656+
* @param self::JPEG|self::PNG|self::GIF|self::WEBP|self::AVIF|self::BMP $type
642657
*/
643658
private function output(int $type, ?int $quality, ?string $file = null): void
644659
{

‎src/Utils/Paginator.php

+19-8
Original file line numberDiff line numberDiff line change
@@ -18,25 +18,27 @@
1818
* @property int $page
1919
* @property-read int $firstPage
2020
* @property-read int|null $lastPage
21-
* @property-read int $firstItemOnPage
22-
* @property-read int $lastItemOnPage
21+
* @property-read int<0,max> $firstItemOnPage
22+
* @property-read int<0,max> $lastItemOnPage
2323
* @property int $base
2424
* @property-read bool $first
2525
* @property-read bool $last
26-
* @property-read int|null $pageCount
27-
* @property int $itemsPerPage
28-
* @property int|null $itemCount
29-
* @property-read int $offset
30-
* @property-read int|null $countdownOffset
31-
* @property-read int $length
26+
* @property-read int<0,max>|null $pageCount
27+
* @property positive-int $itemsPerPage
28+
* @property int<0,max>|null $itemCount
29+
* @property-read int<0,max> $offset
30+
* @property-read int<0,max>|null $countdownOffset
31+
* @property-read int<0,max> $length
3232
*/
3333
class Paginator
3434
{
3535
use Nette\SmartObject;
3636

3737
private int $base = 1;
38+
/** @var positive-int */
3839
private int $itemsPerPage = 1;
3940
private int $page = 1;
41+
/** @var int<0, max>|null */
4042
private ?int $itemCount = null;
4143

4244

@@ -81,6 +83,7 @@ public function getLastPage(): ?int
8183

8284
/**
8385
* Returns the sequence number of the first element on the page
86+
* @return int<0, max>
8487
*/
8588
public function getFirstItemOnPage(): int
8689
{
@@ -92,6 +95,7 @@ public function getFirstItemOnPage(): int
9295

9396
/**
9497
* Returns the sequence number of the last element on the page
98+
* @return int<0, max>
9599
*/
96100
public function getLastItemOnPage(): int
97101
{
@@ -120,6 +124,7 @@ public function getBase(): int
120124

121125
/**
122126
* Returns zero-based page number.
127+
* @return int<0, max>
123128
*/
124129
protected function getPageIndex(): int
125130
{
@@ -152,6 +157,7 @@ public function isLast(): bool
152157

153158
/**
154159
* Returns the total number of pages.
160+
* @return int<0, max>|null
155161
*/
156162
public function getPageCount(): ?int
157163
{
@@ -173,6 +179,7 @@ public function setItemsPerPage(int $itemsPerPage): static
173179

174180
/**
175181
* Returns the number of items to display on a single page.
182+
* @return positive-int
176183
*/
177184
public function getItemsPerPage(): int
178185
{
@@ -192,6 +199,7 @@ public function setItemCount(?int $itemCount = null): static
192199

193200
/**
194201
* Returns the total number of items.
202+
* @return int<0, max>|null
195203
*/
196204
public function getItemCount(): ?int
197205
{
@@ -201,6 +209,7 @@ public function getItemCount(): ?int
201209

202210
/**
203211
* Returns the absolute index of the first item on current page.
212+
* @return int<0, max>
204213
*/
205214
public function getOffset(): int
206215
{
@@ -210,6 +219,7 @@ public function getOffset(): int
210219

211220
/**
212221
* Returns the absolute index of the first item on current page in countdown paging.
222+
* @return int<0, max>|null
213223
*/
214224
public function getCountdownOffset(): ?int
215225
{
@@ -221,6 +231,7 @@ public function getCountdownOffset(): ?int
221231

222232
/**
223233
* Returns the number of items on current page.
234+
* @return int<0, max>
224235
*/
225236
public function getLength(): int
226237
{

‎src/Utils/Random.php

+4
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ final class Random
2222
/**
2323
* Generates a random string of given length from characters specified in second argument.
2424
* Supports intervals, such as `0-9` or `A-Z`.
25+
*
26+
* @param positive-int $length
27+
* @param non-empty-string $charlist
28+
* @return non-empty-string
2529
*/
2630
public static function generate(int $length = 10, string $charlist = '0-9a-z'): string
2731
{

‎src/Utils/Strings.php

+2
Original file line numberDiff line numberDiff line change
@@ -415,6 +415,7 @@ public static function trim(string $s, string $charlist = self::TrimCharacters):
415415

416416
/**
417417
* Pads a UTF-8 string to given length by prepending the $pad string to the beginning.
418+
* @param non-empty-string $pad
418419
*/
419420
public static function padLeft(string $s, int $length, string $pad = ' '): string
420421
{
@@ -426,6 +427,7 @@ public static function padLeft(string $s, int $length, string $pad = ' '): strin
426427

427428
/**
428429
* Pads UTF-8 string to given length by appending the $pad string to the end.
430+
* @param non-empty-string $pad
429431
*/
430432
public static function padRight(string $s, int $length, string $pad = ' '): string
431433
{

‎src/Utils/Validators.php

+5
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,7 @@ public static function everyIs(iterable $values, string $expected): bool
212212

213213
/**
214214
* Checks if the value is an integer or a float.
215+
* @return ($value is int|float ? true : false)
215216
*/
216217
public static function isNumber(mixed $value): bool
217218
{
@@ -221,6 +222,7 @@ public static function isNumber(mixed $value): bool
221222

222223
/**
223224
* Checks if the value is an integer or a integer written in a string.
225+
* @return ($value is non-empty-string ? bool : ($value is int ? true : false))
224226
*/
225227
public static function isNumericInt(mixed $value): bool
226228
{
@@ -230,6 +232,7 @@ public static function isNumericInt(mixed $value): bool
230232

231233
/**
232234
* Checks if the value is a number or a number written in a string.
235+
* @return ($value is non-empty-string ? bool : ($value is int|float ? true : false))
233236
*/
234237
public static function isNumeric(mixed $value): bool
235238
{
@@ -257,6 +260,7 @@ public static function isUnicode(mixed $value): bool
257260

258261
/**
259262
* Checks if the value is 0, '', false or null.
263+
* @return ($value is 0|''|false|null ? true : false)
260264
*/
261265
public static function isNone(mixed $value): bool
262266
{
@@ -274,6 +278,7 @@ public static function isMixed(): bool
274278
/**
275279
* Checks if a variable is a zero-based integer indexed array.
276280
* @deprecated use Nette\Utils\Arrays::isList
281+
* @return ($value is list ? true : false)
277282
*/
278283
public static function isList(mixed $value): bool
279284
{

0 commit comments

Comments
 (0)