improved type annotations (#290)

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
 {
@@ -37,7 +39,7 @@ public static function from(array $array, bool $recursive = true): static
 
 	/**
 	 * Returns an iterator over all items.
-	 * @return \Iterator<int|string, T>
+	 * @return \Iterator<array-key, T>
 	 */
 	public function &getIterator(): \Iterator
 	{
@@ -58,7 +60,7 @@ public function count(): int
 
 	/**
 	 * Replaces or appends a item.
-	 * @param  string|int  $key
+	 * @param  array-key  $key
 	 * @param  T  $value
 	 */
 	public function offsetSet($key, $value): void
@@ -73,7 +75,7 @@ public function offsetSet($key, $value): void
 
 	/**
 	 * Returns a item.
-	 * @param  string|int  $key
+	 * @param  array-key  $key
 	 * @return T
 	 */
 	#[\ReturnTypeWillChange]
@@ -85,7 +87,7 @@ public function offsetGet($key)
 
 	/**
 	 * Determines whether a item exists.
-	 * @param  string|int  $key
+	 * @param  array-key  $key
 	 */
 	public function offsetExists($key): bool
 	{
@@ -95,7 +97,7 @@ public function offsetExists($key): bool
 
 	/**
 	 * Removes the element from this list.
-	 * @param  string|int  $key
+	 * @param  array-key  $key
 	 */
 	public function offsetUnset($key): void
 	{

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
@@ -267,6 +269,7 @@ public static function detectTypeFromString(string $s, &$width = null, &$height
 
 	/**
 	 * Returns the file extension for the given `Image::XXX` constant.
+	 * @return value-of<self::Formats>
 	 */
 	public static function typeToExtension(int $type): string
 	{
@@ -314,6 +317,7 @@ public function __construct(\GdImage $image)
 
 	/**
 	 * Returns image width.
+	 * @return positive-int
 	 */
 	public function getWidth(): int
 	{
@@ -323,6 +327,7 @@ public function getWidth(): int
 
 	/**
 	 * Returns image height.
+	 * @return positive-int
 	 */
 	public function getHeight(): int
 	{
@@ -351,7 +356,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 +393,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 +539,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
 	{

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/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
 	{