Narrow array phpdocs (#2221)

demos/_includes/FakerPersistence.php

@@ -22,13 +22,21 @@ public function __construct()
         $this->faker = FakerFactory::create();
     }
 
+    /**
+     * @return \Traversable<array<string, mixed>>
+     */
     public function prepareIterator(Model $model): \Traversable
     {
         foreach ($this->export($model) as $row) {
             yield $row;
         }
     }
 
+    /**
+     * @param list<string> $fields
+     *
+     * @return list<array<string, mixed>>
+     */
     private function export(Model $model, array $fields = []): array
     {
         if (!$fields) {

demos/_includes/FlyersForm.php

@@ -10,8 +10,10 @@
 
 class FlyersForm extends Form
 {
+    /** @var array<positive-int, array<string, mixed>> */
     public array $flyers = [];
 
+    /** @var list<array<string, mixed>> */
     public array $cards = [
         ['name' => 'Frequent Flyer Program', 'id' => 1, 'nodes' => []],
         ['name' => 'World Class', 'id' => 2, 'nodes' => []],

demos/collection/multitable.php

@@ -21,8 +21,6 @@
 // re-usable component implementing counter
 
 $finderClass = AnonymousClassNameCache::get_class(fn () => new class extends Columns {
-    public array $route = [];
-
     /**
      * @return list<mixed>
      */
@@ -36,6 +34,9 @@ private function explodeSelectionValue(string $value): array
         return $res;
     }
 
+    /**
+     * @param list<string> $route
+     */
     #[\Override]
     public function setModel(Model $model, array $route = []): void
     {

demos/data-action/factory-view.php

@@ -23,6 +23,7 @@
 $myFactory = AnonymousClassNameCache::get_class(fn () => new class extends ExecutorFactory {
     public $buttonPrimaryColor = 'green';
 
+    /** @var array<string, string> */
     protected array $actionIcon = [
         'callback' => 'sync',
         'preview' => 'eye',
@@ -43,7 +44,7 @@ public function __construct()
     }
 
     /**
-     * @return array
+     * @return array<mixed>
      */
     protected function getCardButton(Model\UserAction $action)
     {

demos/interactive/popup.php

@@ -35,6 +35,7 @@
 $cartClass = AnonymousClassNameCache::get_class(fn () => new class extends Lister {
     use SessionTrait;
 
+    /** @var array<int, string> */
     public array $items = [];
 
     public $defaultTemplate = 'lister.html';
@@ -87,8 +88,6 @@ public function removeItem($index): void
     #[\Override]
     protected function renderView(): void
     {
-        // memorize items
-
         $this->setSource($this->items);
 
         parent::renderView();

phpstan.neon.dist

@@ -11,8 +11,6 @@ parameters:
         - js
 
     ignoreErrors:
-        - '~^(Property .+ has|Method .+\(\) (has parameter \$.+ with|return type has)) no value type specified in iterable type .+\.$~'
-
         # relax strict rules
         - '~^Only booleans are allowed in .+, .+ given( on the (left|right) side)?\.$~'
         - '~^Variable (static )?(property access|method call) on .+\.$~'
@@ -374,6 +372,13 @@ parameters:
             message: '~^Call to an undefined method Atk4\\Ui\\Js\\JsChain::addJsonData\(\)\.$~'
             count: 1
 
+        # TODO fix once PHP 7.4 support is dropped
+        -
+            path: 'src/Console.php'
+            identifier: missingType.parameter
+            message: '~^Method Atk4\\Ui\\Console::\w+\(\) has parameter \$message with no type specified\.$~'
+            count: 9
+
         # TODO fix contravariance for View::set() method
         -
             path: 'src/Console.php'
@@ -395,6 +400,11 @@ parameters:
             identifier: method.childParameterType
             message: '~^Parameter #1 \$fx \(Closure\(Atk4\\Ui\\Js\\Jquery, mixed, mixed, mixed, mixed, mixed, mixed, mixed, mixed, mixed, mixed\): \(Atk4\\Ui\\Js\\JsExpressionable\|Atk4\\Ui\\View\|string\|void\)\) of method Atk4\\Ui\\JsCallback::set\(\) should be contravariant with parameter \$fx \(Closure\(mixed, mixed, mixed, mixed, mixed, mixed, mixed, mixed, mixed, mixed\): mixed\) of method Atk4\\Ui\\Callback::set\(\)$~'
             count: 1
+        -
+            path: 'src/JsCallback.php'
+            identifier: method.childParameterType
+            message: '~^Parameter #2 \$args \(array<int\|string, Atk4\\Ui\\Js\\JsExpressionable\|string>\) of method Atk4\\Ui\\JsCallback::set\(\) should be contravariant with parameter \$fxArgs \(list<mixed>\) of method Atk4\\Ui\\Callback::set\(\)$~'
+            count: 1
         -
             path: 'src/Loader.php'
             identifier: method.childParameterType
@@ -606,7 +616,7 @@ parameters:
         -
             path: 'src/Wizard.php'
             identifier: assign.propertyType
-            message: '~^Property Atk4\\Ui\\Wizard::\$steps \(array<int, Atk4\\Ui\\WizardStep>\) does not accept array<int, Atk4\\Ui\\AbstractView>\.$~'
+            message: '~^Property Atk4\\Ui\\Wizard::\$steps \(list<Atk4\\Ui\\WizardStep>\) does not accept non-empty-list<Atk4\\Ui\\AbstractView>\.$~'
             count: 1
 
         # TODO these rules are generated, this ignores should be fixed in the code

src/AbstractView.php

@@ -37,7 +37,7 @@ abstract class AbstractView
      * initialized by calling init() or adding into App or another initialized View,
      * then add() will be re-invoked with the contents of this array.
      *
-     * @var array<int, array{self, array}>|null
+     * @var list<array{self, array<mixed>}>|null
      */
     protected ?array $_addLater = [];
 
@@ -65,6 +65,8 @@ protected function init(): void
     }
 
     /**
+     * @param array<mixed> $args
+     *
      * @return ($object is View ? View : self)
      */
     public function add(self $object, array $args = []): self

src/Accordion.php

@@ -19,13 +19,13 @@ class Accordion extends View
 
     public $ui = 'accordion';
 
-    /** @var array|string|null The CSS class for Fomantic-UI accordion type. */
+    /** @var list<string>|string|null The CSS class for Fomantic-UI accordion type. */
     public $type;
 
-    /** @var array Settings as per Fomantic-UI accordion settings. */
+    /** @var array<string, mixed> Settings as per Fomantic-UI accordion settings. */
     public $settings = [];
 
-    /** @var array A collection of AccordionSection in this Accordion. */
+    /** @var list<AccordionSection> A collection of AccordionSection in this Accordion. */
     public $sections = [];
 
     /** @var int The AccordionSection index number to activate on load. */
@@ -116,8 +116,9 @@ public function jsToggle($section, $when = false): JsExpressionable
      * Ex: toggle an accordion from it's index value.
      * $accordion->jsBehavior('toggle', 1).
      *
-     * @param string $behavior the name of the behavior for the module
-     * @param bool   $when
+     * @param string      $behavior the name of the behavior for the module
+     * @param list<mixed> $args
+     * @param bool        $when
      *
      * @return JsChain
      */

src/App.php

@@ -49,8 +49,8 @@ class App
     private static ?string $shutdownReservedMemory; // @phpstan-ignore property.onlyRead
     private static ?int $errorReportingLevel = null;
 
-    /** @var array|false Location where to load JS/CSS files */
-    public $cdn = [
+    /** @var array<string, string> Location where to load JS/CSS files */
+    public array $cdn = [
         'atk' => '/public',
         'jquery' => '/public/external/jquery/dist',
         'fomantic-ui' => '/public/external/fomantic-ui/dist',
@@ -75,7 +75,7 @@ class App
     /** @var Layout the top-most view object */
     public $layout;
 
-    /** @var string|array Set one or more directories where templates should reside. */
+    /** @var string|list<string> Set one or more directories where templates should reside. */
     public $templateDir;
 
     /** @var bool Will replace an exception handler with our own, that will output errors nicely. */
@@ -140,6 +140,9 @@ class App
     /** @var class-string */
     public $templateClass = HtmlTemplate::class;
 
+    /**
+     * @param array<string, mixed> $defaults
+     */
     public function __construct(array $defaults = [])
     {
         if (isset($defaults['request'])) {
@@ -508,7 +511,7 @@ public function setResponseHeader(string $name, string $value): self
      * directly, instead call it from Callback, JsCallback or similar
      * other classes.
      *
-     * @param string|StreamInterface|array $output Array type is supported only for JSON response
+     * @param string|StreamInterface|array<mixed> $output Array type is supported only for JSON response
      *
      * @return never
      */
@@ -539,7 +542,7 @@ public function terminate($output = ''): void
     }
 
     /**
-     * @param string|array|View|HtmlTemplate $output
+     * @param string|array<mixed>|View|HtmlTemplate $output
      *
      * @return never
      */
@@ -556,7 +559,7 @@ public function terminateHtml($output): void
     }
 
     /**
-     * @param string|array|View $output
+     * @param string|array<mixed>|View $output
      *
      * @return never
      */
@@ -573,7 +576,7 @@ public function terminateJson($output): void
     /**
      * Initializes layout.
      *
-     * @param Layout|array $seed
+     * @param Layout|array<mixed> $seed
      *
      * @return $this
      */
@@ -643,8 +646,8 @@ public function addStyle($style): void
     /**
      * Add a new object into the app. You will need to have Layout first.
      *
-     * @param AbstractView      $object
-     * @param string|array|null $region
+     * @param AbstractView             $object
+     * @param string|array<mixed>|null $region
      *
      * @return ($object is View ? View : AbstractView)
      */
@@ -973,7 +976,7 @@ public function isVoidTag(string $tag): bool
      * --> <a href="hello"><b class="red"><i class="blue">welcome</i></b></a>'
      *
      * @param array<0|string, string|bool>                                                                             $attr
-     * @param string|array<int, array{0: string, 1?: array<0|string, string|bool>, 2?: string|array|null}|string>|null $value
+     * @param string|list<array{0: string, 1?: array<0|string, string|bool>, 2?: string|list<mixed>|null}|string>|null $value
      */
     public function getTag(string $tag, array $attr = [], $value = null): string
     {
@@ -1247,7 +1250,7 @@ private function outputResponseHtml(string $data): void
     }
 
     /**
-     * @param string|array $data
+     * @param string|array<mixed> $data
      */
     private function outputResponseJson($data): void
     {

src/App/SessionManager.php

@@ -24,6 +24,9 @@ protected function isSessionActive(): bool
         return $status === \PHP_SESSION_ACTIVE;
     }
 
+    /**
+     * @return array<string, scalar>
+     */
     protected function createStartSessionOptions(): array
     {
         return [];

src/Behat/Context.php

@@ -101,6 +101,8 @@ protected function getFinishedScript(): string
 
     /**
      * Wait till jQuery AJAX request finished and no animation is perform.
+     *
+     * @param list<mixed> $args
      */
     protected function jqueryWait(string $extraWaitCondition = 'true', array $args = [], int $maxWaitdurationMs = 5000): void
     {

src/Behat/MinkSession.php

@@ -25,18 +25,27 @@ public function getDriver(): MinkSeleniumDriver
         return parent::getDriver(); // @phpstan-ignore return.type
     }
 
+    /**
+     * @param list<mixed> $args
+     */
     #[\Override]
     public function executeScript($script, array $args = []): void
     {
         $this->getDriver()->executeScript($script, $args);
     }
 
+    /**
+     * @param list<mixed> $args
+     */
     #[\Override]
     public function evaluateScript($script, array $args = [])
     {
         return $this->getDriver()->evaluateScript($script, $args);
     }
 
+    /**
+     * @param list<mixed> $args
+     */
     #[\Override]
     public function wait($time, $condition = 'false', array $args = [])
     {

src/Behat/RwDemosContextTrait.php

@@ -30,7 +30,7 @@ trait RwDemosContextTrait
     /** @var array<string, Model>|null */
     protected ?array $databaseBackupModels = null;
 
-    /** @var array<string, array<int, array<string, mixed>>>|null */
+    /** @var array<string, array<positive-int, array<string, mixed>>>|null */
     protected ?array $databaseBackupData = null;
 
     protected function getDemosDb(): Persistence\Sql

src/Breadcrumb.php

@@ -10,7 +10,7 @@ class Breadcrumb extends Lister
 
     public $defaultTemplate = 'breadcrumb.html';
 
-    /** @var array */
+    /** @var list<array{section: string, link: string|array<0|string, string|int|false>}> */
     public $path = [];
 
     /** @var string */
@@ -51,8 +51,8 @@ public function popTitle()
     /**
      * Adds a new link that will appear on the left.
      *
-     * @param string       $section Title of link
-     * @param string|array $link    Link itself
+     * @param string                                   $section Title of link
+     * @param string|array<0|string, string|int|false> $link    Link itself
      *
      * @return $this
      */

src/Button.php

@@ -13,10 +13,10 @@ class Button extends View
 
     public $ui = 'button';
 
-    /** @var string|array|Icon Icon that will appear on the button (left). */
+    /** @var string|array<0|string, mixed>|Icon Icon that will appear on the button (left). */
     public $icon;
 
-    /** @var string|array|Icon Additional icon that can appear on the right of the button. */
+    /** @var string|array<0|string, mixed>|Icon Additional icon that can appear on the right of the button. */
     public $iconRight;
 
     #[\Override]

src/Callback.php

@@ -67,7 +67,7 @@ public function getUrlTrigger(): string
      * @template T
      *
      * @param \Closure(mixed, mixed, mixed, mixed, mixed, mixed, mixed, mixed, mixed, mixed): T $fx
-     * @param array                                                                             $fxArgs
+     * @param list<mixed>                                                                       $fxArgs
      *
      * @return T|null
      */
@@ -146,6 +146,8 @@ public function getUrl(string $value = 'callback'): string
 
     /**
      * Return proper URL argument for this callback.
+     *
+     * @return array<string, string>
      */
     private function getUrlArguments(?string $value = null): array
     {