phpdoc generics for controls

src/Forms/Container.php

@@ -319,6 +319,7 @@ public function getForm(bool $throw = true): ?Form
 
 	/**
 	 * Adds single-line text input control to the form.
+	 * @return Controls\TextInput<string>
 	 */
 	public function addText(
 		string $name,
@@ -334,6 +335,7 @@ public function addText(
 
 	/**
 	 * Adds single-line text input control used for sensitive input such as passwords.
+	 * @return Controls\TextInput<string>
 	 */
 	public function addPassword(
 		string $name,
@@ -350,6 +352,7 @@ public function addPassword(
 
 	/**
 	 * Adds multi-line text input control to the form.
+	 * @return Controls\TextInput<string>
 	 */
 	public function addTextArea(
 		string $name,
@@ -365,6 +368,7 @@ public function addTextArea(
 
 	/**
 	 * Adds input for email.
+	 * @return Controls\TextInput<string>
 	 */
 	public function addEmail(string $name, string|Stringable|null $label = null): Controls\TextInput
 	{
@@ -375,6 +379,7 @@ public function addEmail(string $name, string|Stringable|null $label = null): Co
 
 	/**
 	 * Adds input for integer.
+	 * @return Controls\TextInput<int>
 	 */
 	public function addInteger(string $name, string|Stringable|null $label = null): Controls\TextInput
 	{
@@ -386,6 +391,7 @@ public function addInteger(string $name, string|Stringable|null $label = null):
 
 	/**
 	 * Adds input for float.
+	 * @return Controls\TextInput<float>
 	 */
 	public function addFloat(string $name, string|Stringable|null $label = null): Controls\TextInput
 	{
@@ -434,6 +440,7 @@ public function addDateTime(
 
 	/**
 	 * Adds control that allows the user to upload files.
+	 * @return Controls\UploadControl<Nette\Http\FileUpload>
 	 */
 	public function addUpload(string $name, string|Stringable|null $label = null): Controls\UploadControl
 	{
@@ -443,6 +450,7 @@ public function addUpload(string $name, string|Stringable|null $label = null): C
 
 	/**
 	 * Adds control that allows the user to upload multiple files.
+	 * @return Controls\UploadControl<Nette\Http\FileUpload[]>
 	 */
 	public function addMultiUpload(string $name, string|Stringable|null $label = null): Controls\UploadControl
 	{

src/Forms/Control.php

@@ -12,19 +12,20 @@
 
 /**
  * Defines method that must be implemented to allow a component to act like a form control.
+ * @template T
  */
 interface Control
 {
 	/**
 	 * Sets control's value.
-	 * @param  mixed  $value
+	 * @param  T|null  $value
 	 * @return static
 	 */
 	function setValue(mixed $value);
 
 	/**
 	 * Returns control's value.
-	 * @return mixed
+	 * @return  T|null
 	 */
 	function getValue();
 

src/Forms/Controls/BaseControl.php

@@ -36,6 +36,9 @@
  * @property-read array $errors
  * @property-read array $options
  * @property-read string $error
+ *
+ * @template T
+ * @implements Control<T>
  */
 abstract class BaseControl extends Nette\ComponentModel\Component implements Control
 {
@@ -145,7 +148,6 @@ public function setValue(mixed $value)
 
 	/**
 	 * Returns control's value.
-	 * @return mixed
 	 */
 	public function getValue()
 	{

src/Forms/Controls/Button.php

@@ -15,6 +15,7 @@
 
 /**
  * Push button control with no default behavior.
+ * @extends BaseControl<string>
  */
 class Button extends BaseControl
 {

src/Forms/Controls/Checkbox.php

@@ -16,6 +16,7 @@
 
 /**
  * Check box control. Allows the user to select a true or false condition.
+ * @extends BaseControl<bool>
  */
 class Checkbox extends BaseControl
 {

src/Forms/Controls/ChoiceControl.php

@@ -17,6 +17,8 @@
  *
  * @property   array $items
  * @property-read mixed $selectedItem
+ *
+ * @extends BaseControl<array-key>
  */
 abstract class ChoiceControl extends BaseControl
 {
@@ -71,7 +73,6 @@ public function setValue($value): static
 
 	/**
 	 * Returns selected key.
-	 * @return string|int|null
 	 */
 	public function getValue(): mixed
 	{

src/Forms/Controls/ColorPicker.php

@@ -14,6 +14,7 @@
 
 /**
  * Color picker.
+ * @extends BaseControl<?string>
  */
 class ColorPicker extends BaseControl
 {

src/Forms/Controls/CsrfProtection.php

@@ -16,6 +16,7 @@
 
 /**
  * CSRF protection field.
+ * @extends BaseControl<null>
  */
 class CsrfProtection extends HiddenField
 {

src/Forms/Controls/DateTimeControl.php

@@ -16,6 +16,7 @@
 
 /**
  * Selects date or time or date & time.
+ * @extends BaseControl<\DateTimeInterface|string|int|null>
  */
 class DateTimeControl extends BaseControl
 {

src/Forms/Controls/HiddenField.php

@@ -16,6 +16,7 @@
 
 /**
  * Hidden form control used to store a non-displayed value.
+ * @extends BaseControl<string>
  */
 class HiddenField extends BaseControl
 {

src/Forms/Controls/ImageButton.php

@@ -12,6 +12,7 @@
 
 /**
  * Submittable image button form control.
+ * @method array|null getValue()
  */
 class ImageButton extends SubmitButton
 {

src/Forms/Controls/MultiChoiceControl.php

@@ -17,6 +17,8 @@
  *
  * @property   array $items
  * @property-read array $selectedItems
+ *
+ * @extends BaseControl<array-key[]>
  */
 abstract class MultiChoiceControl extends BaseControl
 {
@@ -83,6 +85,7 @@ public function setValue($values): static
 
 	/**
 	 * Returns selected keys.
+	 * @return array-key[]
 	 */
 	public function getValue(): array
 	{

src/Forms/Controls/TextBase.php

@@ -45,7 +45,6 @@ public function setValue($value): static
 
 	/**
 	 * Returns control's value.
-	 * @return mixed
 	 */
 	public function getValue(): mixed
 	{

tests/types/ControlsReturnTypeTest.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+require __DIR__ . '/../bootstrap.php';
+require __DIR__ . '/TestCase.php';
+
+
+class ControlsReturnTypeTest extends PHPStan\Testing\TypeInferenceTestCase
+{
+	/** @return iterable<mixed> */
+	public function dataFileAsserts(): iterable
+	{
+		yield from $this->gatherAssertTypes(__DIR__ . '/data/Controls.getValue().php');
+	}
+
+
+	/** @dataProvider dataFileAsserts */
+	public function testFileAsserts(string $assertType, string $file, mixed ...$args): void
+	{
+		$this->assertFileAsserts($assertType, $file, ...$args);
+	}
+}
+
+
+$testCase = new ControlsReturnTypeTest;
+$testCase->run();

tests/types/TestCase.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPUnit\Framework;
+
+use Tester\Assert;
+
+
+abstract class TestCase extends \Tester\TestCase
+{
+	protected function assertSame(mixed $expected, mixed $actual, string $message = ''): void
+	{
+		Assert::same($expected, $actual, $message);
+	}
+
+
+	protected function assertTrue(mixed $actual, string $message = ''): void
+	{
+		Assert::true($actual, $message);
+	}
+
+
+	protected function assertInstanceOf(string $expected, object $actual): void
+	{
+		Assert::type($expected, $actual);
+	}
+}

tests/types/data/Controls.getValue().php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+use Nette\Forms\Form;
+use function PHPStan\Testing\assertType;
+
+
+$form = new Form;
+
+$input = $form->addText('text');
+assertType('string|null', $input->getValue());
+
+$input = $form->addPassword('password');
+assertType('string|null', $input->getValue());
+
+$input = $form->addTextArea('textArea');
+assertType('string|null', $input->getValue());
+
+$input = $form->addEmail('email');
+assertType('string|null', $input->getValue());
+
+$input = $form->addInteger('integer');
+assertType('int|null', $input->getValue());
+
+$input = $form->addFloat('float');
+assertType('float|null', $input->getValue());
+
+$input = $form->addDate('date');
+assertType('DateTimeInterface|string|int|null', $input->getValue());
+
+$input = $form->addTime('time');
+assertType('DateTimeInterface|string|int|null', $input->getValue());
+
+$input = $form->addDateTime('dateTime');
+assertType('DateTimeInterface|string|int|null', $input->getValue());
+
+$input = $form->addUpload('upload');
+assertType('array<Nette\Http\FileUpload>|Nette\Http\FileUpload|null', $input->getValue());
+
+$input = $form->addMultiUpload('multiUpload');
+assertType('array<Nette\Http\FileUpload>|Nette\Http\FileUpload|null', $input->getValue());
+
+$input = $form->addHidden('hidden');
+assertType('string|null', $input->getValue());
+
+$input = $form->addCheckbox('checkbox');
+assertType('bool|null', $input->getValue());
+
+$input = $form->addRadioList('radioList');
+assertType('int|string|null', $input->getValue());
+
+$input = $form->addCheckboxList('checkboxList');
+assertType('array<(int|string)>', $input->getValue());
+
+$input = $form->addSelect('select');
+assertType('int|string|null', $input->getValue());
+
+$input = $form->addMultiSelect('multiSelect');
+assertType('array<(int|string)>', $input->getValue());
+
+$input = $form->addColor('color');
+assertType('string|null', $input->getValue());
+
+$input = $form->addSubmit('submit');
+assertType('string|null', $input->getValue());
+
+$input = $form->addButton('button');
+assertType('string|null', $input->getValue());
+
+$input = $form->addImageButton('imageButton');
+assertType('array|null', $input->getValue());
+
+$input = $form->addImage('image');
+assertType('array|null', $input->getValue());