JetBrains · isfedorov · Dec 14, 2024 · Dec 8, 2024 · Dec 8, 2024 · Dec 8, 2024
diff --git a/dom/dom_c.php b/dom/dom_c.php
@@ -58,7 +58,7 @@ class DOMNode
     public $parentNode;
 
     /**
-     * @var DOMNodeList
+     * @var DOMNodeList<DOMNode>
      * A <classname>DOMNodeList</classname> that contains all children of this node. If there are no children, this is an empty <classname>DOMNodeList</classname>.
      * @link https://php.net/manual/en/class.domnode.php#domnode.props.childnodes
      */
@@ -98,7 +98,7 @@ class DOMNode
     public $nextSibling;
 
     /**
-     * @var DOMNamedNodeMap|null
+     * @var DOMNamedNodeMap<DOMAttr>|null
      * A <classname>DOMNamedNodeMap</classname> containing the attributes of this node (if it is a <classname>DOMElement</classname>) or NULL otherwise.
      * @link https://php.net/manual/en/class.domnode.php#domnode.props.attributes
      */
@@ -956,7 +956,7 @@ public function createEntityReference(#[LanguageLevelTypeAware(['8.0' => 'string
      * The name of the tag to match on. The special value *
      * matches all tags.
      * </p>
-     * @return DOMNodeList A new DOMNodeList object containing all the matched
+     * @return DOMNodeList<DOMElement> A new DOMNodeList object containing all the matched
      * elements.
      */
     #[TentativeType]
@@ -1033,7 +1033,7 @@ public function createAttributeNS(
      * The local name of the elements to match on.
      * The special value * matches all local names.
      * </p>
-     * @return DOMNodeList A new DOMNodeList object containing all the matched
+     * @return DOMNodeList<DOMElement> A new DOMNodeList object containing all the matched
      * elements.
      */
     #[TentativeType]
@@ -1328,6 +1328,9 @@ public function registerNodeClass(
 /**
  * The DOMNodeList class
  * @link https://php.net/manual/en/class.domnodelist.php
+ *
+ * @template-covariant TNode of DOMNode|DOMNameSpaceNode
+ * @implements IteratorAggregate<int, TNode>
  */
 class DOMNodeList implements IteratorAggregate, Countable
 {
@@ -1347,7 +1350,7 @@ class DOMNodeList implements IteratorAggregate, Countable
      * Index of the node into the collection.
      * The range of valid child node indices is 0 to length - 1 inclusive.
      * </p>
-     * @return DOMElement|DOMNode|DOMNameSpaceNode|null The node at the indexth position in the
+     * @return TNode|null The node at the indexth position in the
      * DOMNodeList, or null if that is not a valid
      * index.
      */
@@ -1361,7 +1364,7 @@ public function item(#[LanguageLevelTypeAware(['8.0' => 'int'], default: '')] $i
     public function count(): int {}
 
     /**
-     * @return Iterator
+     * @return Iterator<int, TNode>
      * @since 8.0
      */
     public function getIterator(): Iterator {}
@@ -1371,6 +1374,9 @@ public function getIterator(): Iterator {}
  * The DOMNamedNodeMap class
  * @link https://php.net/manual/en/class.domnamednodemap.php
  * @property-read int $length The number of nodes in the map. The range of valid child node indices is 0 to length - 1 inclusive.
+ *
+ * @template-covariant TNode of DOMNode
+ * @implements IteratorAggregate<string, TNode>
  */
 class DOMNamedNodeMap implements IteratorAggregate, Countable
 {
@@ -1380,18 +1386,21 @@ class DOMNamedNodeMap implements IteratorAggregate, Countable
      * @param string $qualifiedName <p>
      * The nodeName of the node to retrieve.
      * </p>
-     * @return DOMNode|null A node (of any type) with the specified nodeName, or
+     * @return TNode|null A node (of any type) with the specified nodeName, or
      * null if no node is found.
      */
     #[TentativeType]
     public function getNamedItem(#[LanguageLevelTypeAware(['8.0' => 'string'], default: '')] $qualifiedName): ?DOMNode {}
 
     /**
+     * @removed 8.0
      * @param DOMNode $arg
+     * @return void
      */
     public function setNamedItem(DOMNode $arg) {}
 
     /**
+     * @removed 8.0
      * @param $name [optional]
      */
     public function removeNamedItem($name) {}
@@ -1421,7 +1430,7 @@ public function item(
      * @param string $localName <p>
      * The local name of the node to retrieve.
      * </p>
-     * @return DOMNode|null A node (of any type) with the specified local name and namespace URI, or
+     * @return TNode|null A node (of any type) with the specified local name and namespace URI, or
      * null if no node is found.
      */
     #[TentativeType]
@@ -1433,11 +1442,13 @@ public function getNamedItemNS(
     ): ?DOMNode {}
 
     /**
+     * @removed 8.0
      * @param DOMNode $arg [optional]
      */
     public function setNamedItemNS(DOMNode $arg) {}
 
     /**
+     * @removed 8.0
      * @param $namespace [optional]
      * @param $localName [optional]
      */
@@ -1451,7 +1462,7 @@ public function removeNamedItemNS($namespace, $localName) {}
     public function count(): int {}
 
     /**
-     * @return Iterator
+     * @return Iterator<string, TNode>
      * @since 8.0
      */
     public function getIterator(): Iterator {}
@@ -1709,7 +1720,7 @@ class DOMElement extends DOMNode implements DOMParentNode, DOMChildNode
     public $nextSibling;
 
     /**
-     * @var DOMNamedNodeMap
+     * @var DOMNamedNodeMap<DOMAttr>
      * A <classname>DOMNamedNodeMap</classname> containing the attributes of this node (if it is a <classname>DOMElement</classname>) or NULL otherwise.
      * @link https://php.net/manual/en/class.domnode.php#domnode.props.attributes
      */
@@ -1825,7 +1836,7 @@ public function removeAttributeNode(DOMAttr $attr) {}
      * The tag name. Use * to return all elements within
      * the element tree.
      * </p>
-     * @return DOMNodeList This function returns a new instance of the class
+     * @return DOMNodeList<DOMElement> This function returns a new instance of the class
      * DOMNodeList of all matched elements.
      */
     #[TentativeType]
@@ -1922,7 +1933,7 @@ public function setAttributeNodeNS(DOMAttr $attr) {}
      * The local name. Use * to return all elements within
      * the element tree.
      * </p>
-     * @return DOMNodeList This function returns a new instance of the class
+     * @return DOMNodeList<DOMElement> This function returns a new instance of the class
      * DOMNodeList of all matched elements in the order in
      * which they are encountered in a preorder traversal of this element tree.
      */
@@ -2252,15 +2263,15 @@ class DOMDocumentType extends DOMNode
     public $name;
 
     /**
-     * @var DOMNamedNodeMap
+     * @var DOMNamedNodeMap<DOMEntity>
      * A <classname>DOMNamedNodeMap</classname> containing the general entities, both external and internal, declared in the DTD.
      * @link https://php.net/manual/en/class.domdocumenttype.php#domdocumenttype.props.entities
      */
     #[LanguageLevelTypeAware(['8.1' => 'DOMNamedNodeMap'], default: '')]
     public $entities;
 
     /**
-     * @var DOMNamedNodeMap
+     * @var DOMNamedNodeMap<DOMNotation>
      * A <clasname>DOMNamedNodeMap</classname> containing the notations declared in the DTD.
      * @link https://php.net/manual/en/class.domdocumenttype.php#domdocumenttype.props.notations
      */
@@ -2473,7 +2484,7 @@ public function registerNamespace(
      * </p>
      * @param bool $registerNodeNS [optional] <p>The optional registerNodeNS can be specified to
      * disable automatic registration of the context node.</p>
-     * @return DOMNodeList|false a DOMNodeList containing all nodes matching
+     * @return DOMNodeList<DOMNode|DOMNameSpaceNode>|false a DOMNodeList containing all nodes matching
      * the given XPath expression. Any expression which does not return nodes
      * will return an empty DOMNodeList. The return is false if the expression
      * is malformed or the contextnode is invalid.
@@ -2500,7 +2511,7 @@ public function query(
      * <p>
      * The optional registerNodeNS can be specified to disable automatic registration of the context node.
      * </p>
-     * @return mixed a typed result if possible or a DOMNodeList
+     * @return mixed a typed result if possible or a DOMNodeList<DOMNode|DOMNameSpaceNode>|false
      * containing all nodes matching the given XPath expression.
      */
     #[TentativeType]

diff --git a/dom/dom_n.php b/dom/dom_n.php
@@ -28,19 +28,26 @@ private function __construct() {}
 
 /**
  * @since 8.4
+ * @template TNode of Node Should be template-covariant but DocBlock::getTagsByName() does not support it
+ * @implements \IteratorAggregate<int, TNode>
  */
 class NodeList implements \IteratorAggregate, \Countable
 {
     public int $length;
 
     public function count(): int {}
 
+    /**
+     * @return \Iterator<int, TNode>
+     */
     public function getIterator(): \Iterator {}
 
+    /** @return TNode|null */
     public function item(int $index): ?Node {}
 }
 /**
  * @since 8.4
+ * @implements \IteratorAggregate<array-key, Attr>
  */
 class NamedNodeMap implements \IteratorAggregate, \Countable
 {
@@ -54,27 +61,38 @@ public function getNamedItemNS(?string $namespace, string $localName): ?Attr {}
 
     public function count(): int {}
 
+    /**
+     * @return \Iterator<array-key, Attr>
+     */
     public function getIterator(): \Iterator {}
 }
 /**
  * @since 8.4
+ *
+ * @template TDtdNode of Entity|Notation Should be template-covariant but DocBlock::getTagsByName() does not support it
+ * @implements \IteratorAggregate<string, TDtdNode>
  */
 class DtdNamedNodeMap implements \IteratorAggregate, \Countable
 {
     public int $length;
 
+    /** @return TDtdNode|null */
     public function item(int $index): Entity|Notation|null {}
 
+    /** @return TDtdNode|null */
     public function getNamedItem(string $qualifiedName): Entity|Notation|null {}
 
+    /** @return TDtdNode|null */
     public function getNamedItemNS(?string $namespace, string $localName): Entity|Notation|null {}
 
     public function count(): int {}
 
+    /** @return \Iterator<string, TDtdNode> */
     public function getIterator(): \Iterator {}
 }
 /**
  * @since 8.4
+ * @implements \IteratorAggregate<array-key, Element>
  */
 class HTMLCollection implements \IteratorAggregate, \Countable
 {
@@ -86,6 +104,9 @@ public function namedItem(string $key): ?Element {}
 
     public function count(): int {}
 
+    /**
+     * @return \Iterator<array-key, Element>
+     */
     public function getIterator(): \Iterator {}
 }
 /**
@@ -98,8 +119,10 @@ final class XPath
 
     public function __construct(Document $document, bool $registerNodeNS = true) {}
 
+    /** @return null|bool|float|string|NodeList<Node> */
     public function evaluate(string $expression, ?Node $contextNode = null, bool $registerNodeNS = true): null|bool|float|string|NodeList {}
 
+    /** @return NodeList<Node> */
     public function query(string $expression, ?Node $contextNode = null, bool $registerNodeNS = true): NodeList {}
 
     public function registerNamespace(string $prefix, string $namespace): bool {}
@@ -150,6 +173,7 @@ public function replaceChildren(Node|string ...$nodes): void;
 
     public function querySelector(string $selectors): ?Element;
 
+    /** @return NodeList<Element> */
     public function querySelectorAll(string $selectors): NodeList;
 }
 /**
@@ -198,6 +222,8 @@ public function getRootNode(array $options = []): Node {}
     public ?Element $parentElement;
 
     public function hasChildNodes(): bool {}
+
+    /** @var NodeList<Node> */
     public NodeList $childNodes;
     public ?Node $firstChild;
     public ?Node $lastChild;
@@ -269,6 +295,7 @@ public function replaceChildren(Node|string ...$nodes): void {}
 
     public function querySelector(string $selectors): ?Element {}
 
+    /** @return NodeList<Element> */
     public function querySelectorAll(string $selectors): NodeList {}
 }
 /**
@@ -337,6 +364,7 @@ public function importLegacyNode(\DOMNode $node, bool $deep = false): Node {}
 
     public function querySelector(string $selectors): ?Element {}
 
+    /** @return NodeList<Element> */
     public function querySelectorAll(string $selectors): NodeList {}
     public ?HTMLElement $body;
     public ?HTMLElement $head;
@@ -516,6 +544,7 @@ public function replaceChildren(Node|string ...$nodes): void {}
 
     public function querySelector(string $selectors): ?Element {}
 
+    /** @return NodeList<Element> */
     public function querySelectorAll(string $selectors): NodeList {}
 
     public function closest(string $selectors): ?Element {}
@@ -525,10 +554,10 @@ public function matches(string $selectors): bool {}
     public string $outerHTML;
     public string $substitutedNodeValue;
 
-    /** @return array<NamespaceInfo> */
+    /** @return list<NamespaceInfo> */
     public function getInScopeNamespaces(): array {}
 
-    /** @return array<NamespaceInfo> */
+    /** @return list<NamespaceInfo> */
     public function getDescendantNamespaces(): array {}
 
     public function rename(?string $namespaceURI, string $qualifiedName): void {}

diff --git a/mysql/mysql.php b/mysql/mysql.php
@@ -444,7 +444,7 @@ function mysql_fetch_array($result, $result_type = MYSQL_BOTH) {}
 function mysql_fetch_assoc($result) {}
 
 /**
- * @template T
+ * @template T of object
  *
  * Fetch a result row as an object
  * @link https://php.net/manual/en/function.mysql-fetch-object.php

diff --git a/mysqli/mysqli.php b/mysqli/mysqli.php
@@ -1332,7 +1332,7 @@ public function fetch_array(#[LanguageLevelTypeAware(['8.0' => 'int'], default:
     public function fetch_assoc(): array|false|null {}
 
     /**
-     * @template T
+     * @template T of object
      *
      * Fetch the next row of a result set as an object
      * @link https://php.net/manual/en/mysqli-result.fetch-object.php
@@ -2052,7 +2052,7 @@ function mysqli_fetch_array(mysqli_result $result, int $mode = MYSQLI_BOTH): arr
 function mysqli_fetch_assoc(mysqli_result $result): array|null|false {}
 
 /**
- * @template T
+ * @template T of object
  *
  * Fetch the next row of a result set as an object
  * @link https://php.net/manual/en/mysqli-result.fetch-object.php

diff --git a/tests/Model/CommonUtils.php b/tests/Model/CommonUtils.php
@@ -17,5 +17,15 @@ public static function flattenArray(array $array, $group)
         return iterator_to_array(new RecursiveIteratorIterator(new RecursiveArrayIterator($array)), $group);
     }
 
-    public function array_flat_map(array $array, $callback) {}
+    /**
+     * @template T
+     * @template S
+     *
+     * @param list<T> $array
+     * @param callable(T): list<S> $callback
+     * @return list<S>
+     */
+    public static function array_flat_map(array $array, callable $callback) {
+        return array_merge(...array_map($callback, $array));
+    }
 }