Improve type annotations (#290)

* added enum ImageType

* Finder: default mask is '*'

* Finder: improved exception when directory is missing

* Finder: collect() returns list

* Finder: removed slashes normalization

* Improve type annotations

---------

Co-authored-by: David Grudl <[email protected]>

Author: xificurk

src/Utils/ArrayHash.php

@@ -15,6 +15,8 @@
 /**
  * Provides objects to work as array.
  * @template T
+ * @implements \IteratorAggregate<array-key, T>
+ * @implements \ArrayAccess<array-key, T>
  */
 class ArrayHash extends \stdClass implements \ArrayAccess, \Countable, \IteratorAggregate
 {

src/Utils/ArrayList.php

@@ -15,6 +15,8 @@
 /**
  * Provides the base class for a generic list (items can be accessed by index).
  * @template T
+ * @implements \IteratorAggregate<int, T>
+ * @implements \ArrayAccess<int, T>
  */
 class ArrayList implements \ArrayAccess, \Countable, \IteratorAggregate
 {
@@ -25,7 +27,7 @@ class ArrayList implements \ArrayAccess, \Countable, \IteratorAggregate
 
 	/**
 	 * Transforms array to ArrayList.
-	 * @param  array<T>  $array
+	 * @param  list<T>  $array
 	 */
 	public static function from(array $array): static
 	{

src/Utils/Arrays.php

@@ -225,6 +225,7 @@ public static function flatten(array $array, bool $preserveKeys = false): array
 
 	/**
 	 * Checks if the array is indexed in ascending order of numeric keys from zero, a.k.a list.
+	 * @return ($value is list ? true : false)
 	 */
 	public static function isList(mixed $value): bool
 	{

src/Utils/Image.php

@@ -90,8 +90,8 @@
  * @method void stringUp($font, $x, $y, string $s, $col)
  * @method void trueColorToPalette(bool $dither, $ncolors)
  * @method array ttfText($size, $angle, $x, $y, $color, string $fontfile, string $text)
- * @property-read int $width
- * @property-read int $height
+ * @property-read positive-int $width
+ * @property-read positive-int $height
  * @property-read \GdImage $imageResource
  */
 class Image
@@ -220,6 +220,8 @@ private static function invokeSafe(string $func, string $arg, string $message, s
 
 	/**
 	 * Creates a new true color image of the given dimensions. The default color is black.
+	 * @param positive-int $width
+	 * @param positive-int $height
 	 * @throws Nette\NotSupportedException if gd extension is not loaded
 	 */
 	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):
 
 	/**
 	 * Returns the type of image from file.
+	 * @return ImageType::*|null
 	 */
 	public static function detectTypeFromFile(string $file, &$width = null, &$height = null): ?int
 	{
@@ -257,6 +260,7 @@ public static function detectTypeFromFile(string $file, &$width = null, &$height
 
 	/**
 	 * Returns the type of image from string.
+	 * @return ImageType::*|null
 	 */
 	public static function detectTypeFromString(string $s, &$width = null, &$height = null): ?int
 	{
@@ -267,6 +271,8 @@ public static function detectTypeFromString(string $s, &$width = null, &$height
 
 	/**
 	 * Returns the file extension for the given `ImageType::XXX` constant.
+	 * @param ImageType::* $type
+	 * @return value-of<self::Formats>
 	 */
 	public static function typeToExtension(int $type): string
 	{
@@ -280,6 +286,7 @@ public static function typeToExtension(int $type): string
 
 	/**
 	 * Returns the `ImageType::XXX` constant for given file extension.
+	 * @return ImageType::*
 	 */
 	public static function extensionToType(string $extension): int
 	{
@@ -295,6 +302,7 @@ public static function extensionToType(string $extension): int
 
 	/**
 	 * Returns the mime type for the given `ImageType::XXX` constant.
+	 * @param ImageType::* $type
 	 */
 	public static function typeToMimeType(int $type): string
 	{
@@ -314,6 +322,7 @@ public function __construct(\GdImage $image)
 
 	/**
 	 * Returns image width.
+	 * @return positive-int
 	 */
 	public function getWidth(): int
 	{
@@ -323,6 +332,7 @@ public function getWidth(): int
 
 	/**
 	 * Returns image height.
+	 * @return positive-int
 	 */
 	public function getHeight(): int
 	{
@@ -351,7 +361,7 @@ public function getImageResource(): \GdImage
 
 	/**
 	 * Scales an image. Width and height accept pixels or percent.
-	 * @param  self::OrSmaller|self::OrBigger|self::Stretch|self::Cover|self::ShrinkOnly  $mode
+	 * @param  int-mask-of<self::OrSmaller|self::OrBigger|self::Stretch|self::Cover|self::ShrinkOnly>  $mode
 	 */
 	public function resize(int|string|null $width, int|string|null $height, int $mode = self::OrSmaller): static
 	{
@@ -388,7 +398,7 @@ public function resize(int|string|null $width, int|string|null $height, int $mod
 
 	/**
 	 * Calculates dimensions of resized image. Width and height accept pixels or percent.
-	 * @param  self::OrSmaller|self::OrBigger|self::Stretch|self::Cover|self::ShrinkOnly  $mode
+	 * @param  int-mask-of<self::OrSmaller|self::OrBigger|self::Stretch|self::Cover|self::ShrinkOnly>  $mode
 	 */
 	public static function calculateSize(
 		int $srcWidth,
@@ -534,7 +544,7 @@ public function sharpen(): static
 
 	/**
 	 * Puts another image into this image. Left and top accepts pixels or percent.
-	 * @param  int  $opacity 0..100
+	 * @param  int<0, 100>  $opacity 0..100
 	 */
 	public function place(self $image, int|string $left = 0, int|string $top = 0, int $opacity = 100): static
 	{
@@ -596,6 +606,7 @@ public function place(self $image, int|string $left = 0, int|string $top = 0, in
 
 	/**
 	 * 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).
+	 * @param ImageType::*|null $type
 	 * @throws ImageException
 	 */
 	public function save(string $file, ?int $quality = null, ?int $type = null): void
@@ -607,6 +618,7 @@ public function save(string $file, ?int $quality = null, ?int $type = null): voi
 
 	/**
 	 * 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).
+	 * @param ImageType::* $type
 	 */
 	public function toString(int $type = ImageType::JPEG, ?int $quality = null): string
 	{
@@ -627,6 +639,7 @@ public function __toString(): string
 
 	/**
 	 * 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).
+	 * @param ImageType::* $type
 	 * @throws ImageException
 	 */
 	public function send(int $type = ImageType::JPEG, ?int $quality = null): void
@@ -639,6 +652,7 @@ public function send(int $type = ImageType::JPEG, ?int $quality = null): void
 	/**
 	 * Outputs image to browser or file.
 	 * @throws ImageException
+	 * @param ImageType::* $type
 	 */
 	private function output(int $type, ?int $quality, ?string $file = null): void
 	{

src/Utils/Paginator.php

@@ -18,25 +18,30 @@
  * @property   int $page
  * @property-read int $firstPage
  * @property-read int|null $lastPage
- * @property-read int $firstItemOnPage
- * @property-read int $lastItemOnPage
+ * @property-read int<0,max> $firstItemOnPage
+ * @property-read int<0,max> $lastItemOnPage
  * @property   int $base
  * @property-read bool $first
  * @property-read bool $last
- * @property-read int|null $pageCount
- * @property   int $itemsPerPage
- * @property   int|null $itemCount
- * @property-read int $offset
- * @property-read int|null $countdownOffset
- * @property-read int $length
+ * @property-read int<0,max>|null $pageCount
+ * @property   positive-int $itemsPerPage
+ * @property   int<0,max>|null $itemCount
+ * @property-read int<0,max> $offset
+ * @property-read int<0,max>|null $countdownOffset
+ * @property-read int<0,max> $length
  */
 class Paginator
 {
 	use Nette\SmartObject;
 
 	private int $base = 1;
+
+	/** @var positive-int */
 	private int $itemsPerPage = 1;
+
 	private int $page = 1;
+
+	/** @var int<0, max>|null */
 	private ?int $itemCount = null;
 
 
@@ -81,6 +86,7 @@ public function getLastPage(): ?int
 
 	/**
 	 * Returns the sequence number of the first element on the page
+	 * @return int<0, max>
 	 */
 	public function getFirstItemOnPage(): int
 	{
@@ -92,6 +98,7 @@ public function getFirstItemOnPage(): int
 
 	/**
 	 * Returns the sequence number of the last element on the page
+	 * @return int<0, max>
 	 */
 	public function getLastItemOnPage(): int
 	{
@@ -120,6 +127,7 @@ public function getBase(): int
 
 	/**
 	 * Returns zero-based page number.
+	 * @return int<0, max>
 	 */
 	protected function getPageIndex(): int
 	{
@@ -152,6 +160,7 @@ public function isLast(): bool
 
 	/**
 	 * Returns the total number of pages.
+	 * @return int<0, max>|null
 	 */
 	public function getPageCount(): ?int
 	{
@@ -173,6 +182,7 @@ public function setItemsPerPage(int $itemsPerPage): static
 
 	/**
 	 * Returns the number of items to display on a single page.
+	 * @return positive-int
 	 */
 	public function getItemsPerPage(): int
 	{
@@ -192,6 +202,7 @@ public function setItemCount(?int $itemCount = null): static
 
 	/**
 	 * Returns the total number of items.
+	 * @return int<0, max>|null
 	 */
 	public function getItemCount(): ?int
 	{
@@ -201,6 +212,7 @@ public function getItemCount(): ?int
 
 	/**
 	 * Returns the absolute index of the first item on current page.
+	 * @return int<0, max>
 	 */
 	public function getOffset(): int
 	{
@@ -210,6 +222,7 @@ public function getOffset(): int
 
 	/**
 	 * Returns the absolute index of the first item on current page in countdown paging.
+	 * @return int<0, max>|null
 	 */
 	public function getCountdownOffset(): ?int
 	{
@@ -221,6 +234,7 @@ public function getCountdownOffset(): ?int
 
 	/**
 	 * Returns the number of items on current page.
+	 * @return int<0, max>
 	 */
 	public function getLength(): int
 	{

src/Utils/Random.php

@@ -22,6 +22,10 @@ final class Random
 	/**
 	 * Generates a random string of given length from characters specified in second argument.
 	 * Supports intervals, such as `0-9` or `A-Z`.
+	 *
+	 * @param positive-int $length
+	 * @param non-empty-string $charlist
+	 * @return non-empty-string
 	 */
 	public static function generate(int $length = 10, string $charlist = '0-9a-z'): string
 	{

src/Utils/Strings.php

@@ -415,6 +415,7 @@ public static function trim(string $s, string $charlist = self::TrimCharacters):
 
 	/**
 	 * Pads a UTF-8 string to given length by prepending the $pad string to the beginning.
+	 * @param non-empty-string $pad
 	 */
 	public static function padLeft(string $s, int $length, string $pad = ' '): string
 	{
@@ -426,6 +427,7 @@ public static function padLeft(string $s, int $length, string $pad = ' '): strin
 
 	/**
 	 * Pads UTF-8 string to given length by appending the $pad string to the end.
+	 * @param non-empty-string $pad
 	 */
 	public static function padRight(string $s, int $length, string $pad = ' '): string
 	{

src/Utils/Validators.php

@@ -212,6 +212,7 @@ public static function everyIs(iterable $values, string $expected): bool
 
 	/**
 	 * Checks if the value is an integer or a float.
+	 * @return ($value is int|float ? true : false)
 	 */
 	public static function isNumber(mixed $value): bool
 	{
@@ -221,6 +222,7 @@ public static function isNumber(mixed $value): bool
 
 	/**
 	 * Checks if the value is an integer or a integer written in a string.
+	 * @return ($value is non-empty-string ? bool : ($value is int ? true : false))
 	 */
 	public static function isNumericInt(mixed $value): bool
 	{
@@ -230,6 +232,7 @@ public static function isNumericInt(mixed $value): bool
 
 	/**
 	 * Checks if the value is a number or a number written in a string.
+	 * @return ($value is non-empty-string ? bool : ($value is int|float ? true : false))
 	 */
 	public static function isNumeric(mixed $value): bool
 	{
@@ -257,6 +260,7 @@ public static function isUnicode(mixed $value): bool
 
 	/**
 	 * Checks if the value is 0, '', false or null.
+	 * @return ($value is 0|''|false|null ? true : false)
 	 */
 	public static function isNone(mixed $value): bool
 	{
@@ -274,6 +278,7 @@ public static function isMixed(): bool
 	/**
 	 * Checks if a variable is a zero-based integer indexed array.
 	 * @deprecated  use Nette\Utils\Arrays::isList
+	 * @return ($value is list ? true : false)
 	 */
 	public static function isList(mixed $value): bool
 	{