Skip to content

Commit d2ccf32

Browse files
nicolas-grekasnicolas-grekas
committed
minor #61482 [DomCrawler] Improve phpdoc annotations (nicolas-grekas)
This PR was merged into the 7.4 branch. Discussion ---------- [DomCrawler] Improve phpdoc annotations | Q | A | ------------- | --- | Branch? | 7.4 | Bug fix? | no | New feature? | no | Deprecations? | no | Issues | - | License | MIT Subset of #61356 Commits ------- c06142a [DomCrawler] Improve phpdoc annotations
2 parents 8187625 + c06142a commit d2ccf32

File tree

2 files changed

+45
-26
lines changed

2 files changed

+45
-26
lines changed

‎.github/expected-missing-return-types.diff

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,23 @@ diff --git a/src/Symfony/Component/DependencyInjection/Extension/PrependExtensio
187187
- public function prepend(ContainerBuilder $container);
188188
+ public function prepend(ContainerBuilder $container): void;
189189
}
190+
diff --git a/src/Symfony/Component/DomCrawler/Crawler.php b/src/Symfony/Component/DomCrawler/Crawler.php
191+
--- a/src/Symfony/Component/DomCrawler/Crawler.php
192+
+++ b/src/Symfony/Component/DomCrawler/Crawler.php
193+
@@ -405,5 +405,5 @@ class Crawler implements \Countable, \IteratorAggregate
194+
* @throws \InvalidArgumentException When current node is empty
195+
*/
196+
- public function closest(string $selector): ?self
197+
+ public function closest(string $selector): ?static
198+
{
199+
if (!$this->nodes) {
200+
@@ -646,5 +646,5 @@ class Crawler implements \Countable, \IteratorAggregate
201+
* @return array|static
202+
*/
203+
- public function evaluate(string $xpath): array|self
204+
+ public function evaluate(string $xpath): array|static
205+
{
206+
if (null === $this->document) {
190207
diff --git a/src/Symfony/Component/Emoji/EmojiTransliterator.php b/src/Symfony/Component/Emoji/EmojiTransliterator.php
191208
--- a/src/Symfony/Component/Emoji/EmojiTransliterator.php
192209
+++ b/src/Symfony/Component/Emoji/EmojiTransliterator.php

‎src/Symfony/Component/DomCrawler/Crawler.php

Lines changed: 28 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,13 @@ class Crawler implements \Countable, \IteratorAggregate
3737

3838
/**
3939
* A map of cached namespaces.
40+
*
41+
* @var \ArrayObject<string, string|null>
4042
*/
4143
private \ArrayObject $cachedNamespaces;
4244

4345
private ?string $baseHref;
46+
4447
private ?\DOMDocument $document = null;
4548

4649
/**
@@ -56,7 +59,7 @@ class Crawler implements \Countable, \IteratorAggregate
5659
private ?HTML5 $html5Parser = null;
5760

5861
/**
59-
* @param \DOMNodeList|\DOMNode|\DOMNode[]|string|null $node A Node to use as the base for the crawling
62+
* @param \DOMNodeList<\DOMNode>|\DOMNode|\DOMNode[]|string|null $node A Node to use as the base for the crawling
6063
*/
6164
public function __construct(
6265
\DOMNodeList|\DOMNode|array|string|null $node = null,
@@ -107,9 +110,7 @@ public function clear(): void
107110
* This method uses the appropriate specialized add*() method based
108111
* on the type of the argument.
109112
*
110-
* @param \DOMNodeList|\DOMNode|\DOMNode[]|string|null $node A node
111-
*
112-
* @throws \InvalidArgumentException when node is not the expected type
113+
* @param \DOMNodeList<\DOMNode>|\DOMNode|\DOMNode[]|string|null $node
113114
*/
114115
public function add(\DOMNodeList|\DOMNode|array|string|null $node): void
115116
{
@@ -121,8 +122,6 @@ public function add(\DOMNodeList|\DOMNode|array|string|null $node): void
121122
$this->addNodes($node);
122123
} elseif (\is_string($node)) {
123124
$this->addContent($node);
124-
} elseif (null !== $node) {
125-
throw new \InvalidArgumentException(\sprintf('Expecting a DOMNodeList or DOMNode instance, an array, a string, or null, but got "%s".', get_debug_type($node)));
126125
}
127126
}
128127

@@ -232,8 +231,6 @@ public function addXmlContent(string $content, string $charset = 'UTF-8', int $o
232231

233232
/**
234233
* Adds a \DOMDocument to the list of nodes.
235-
*
236-
* @param \DOMDocument $dom A \DOMDocument instance
237234
*/
238235
public function addDocument(\DOMDocument $dom): void
239236
{
@@ -245,7 +242,7 @@ public function addDocument(\DOMDocument $dom): void
245242
/**
246243
* Adds a \DOMNodeList to the list of nodes.
247244
*
248-
* @param \DOMNodeList $nodes A \DOMNodeList instance
245+
* @param \DOMNodeList<\DOMNode> $nodes
249246
*/
250247
public function addNodeList(\DOMNodeList $nodes): void
251248
{
@@ -259,7 +256,7 @@ public function addNodeList(\DOMNodeList $nodes): void
259256
/**
260257
* Adds an array of \DOMNode instances to the list of nodes.
261258
*
262-
* @param \DOMNode[] $nodes An array of \DOMNode instances
259+
* @param \DOMNode[] $nodes
263260
*/
264261
public function addNodes(array $nodes): void
265262
{
@@ -270,8 +267,6 @@ public function addNodes(array $nodes): void
270267

271268
/**
272269
* Adds a \DOMNode instance to the list of nodes.
273-
*
274-
* @param \DOMNode $node A \DOMNode instance
275270
*/
276271
public function addNode(\DOMNode $node): void
277272
{
@@ -313,13 +308,13 @@ public function eq(int $position): static
313308
*
314309
* Example:
315310
*
316-
* $crawler->filter('h1')->each(function ($node, $i) {
317-
* return $node->text();
318-
* });
311+
* $crawler->filter('h1')->each(fn ($node, $i) => $node->text());
312+
*
313+
* @template R of mixed
319314
*
320-
* @param \Closure $closure An anonymous function
315+
* @param \Closure(static, int):R $closure
321316
*
322-
* @return array An array of values returned by the anonymous function
317+
* @return list<R> An array of values returned by the anonymous function
323318
*/
324319
public function each(\Closure $closure): array
325320
{
@@ -344,7 +339,7 @@ public function slice(int $offset = 0, ?int $length = null): static
344339
*
345340
* To remove a node from the list, the anonymous function must return false.
346341
*
347-
* @param \Closure $closure An anonymous function
342+
* @param \Closure(static, int):bool $closure
348343
*/
349344
public function reduce(\Closure $closure): static
350345
{
@@ -377,7 +372,7 @@ public function last(): static
377372
/**
378373
* Returns the siblings nodes of the current selection.
379374
*
380-
* @throws \InvalidArgumentException When current node is empty
375+
* @throws \InvalidArgumentException When the current node is empty
381376
*/
382377
public function siblings(): static
383378
{
@@ -405,6 +400,8 @@ public function matches(string $selector): bool
405400
*
406401
* @see https://developer.mozilla.org/en-US/docs/Web/API/Element/closest#Polyfill
407402
*
403+
* @return ?static
404+
*
408405
* @throws \InvalidArgumentException When current node is empty
409406
*/
410407
public function closest(string $selector): ?self
@@ -444,7 +441,7 @@ public function nextAll(): static
444441
/**
445442
* Returns the previous sibling nodes of the current selection.
446443
*
447-
* @throws \InvalidArgumentException
444+
* @throws \InvalidArgumentException When current node is empty
448445
*/
449446
public function previousAll(): static
450447
{
@@ -481,7 +478,7 @@ public function ancestors(): static
481478
/**
482479
* Returns the children nodes of the current selection.
483480
*
484-
* @throws \InvalidArgumentException When current node is empty
481+
* @throws \InvalidArgumentException When the current node is empty
485482
* @throws \RuntimeException If the CssSelector Component is not available and $selector is provided
486483
*/
487484
public function children(?string $selector = null): static
@@ -527,7 +524,7 @@ public function attr(string $attribute, ?string $default = null): ?string
527524
/**
528525
* Returns the node name of the first node of the list.
529526
*
530-
* @throws \InvalidArgumentException When current node is empty
527+
* @throws \InvalidArgumentException When the current node is empty
531528
*/
532529
public function nodeName(): string
533530
{
@@ -594,7 +591,7 @@ public function innerText(bool $normalizeWhitespace = true): string
594591
*
595592
* @param string|null $default When not null: the value to return when the current node is empty
596593
*
597-
* @throws \InvalidArgumentException When current node is empty
594+
* @throws \InvalidArgumentException When the current node is empty
598595
*/
599596
public function html(?string $default = null): string
600597
{
@@ -621,6 +618,9 @@ public function html(?string $default = null): string
621618
return $html;
622619
}
623620

621+
/**
622+
* @throws \InvalidArgumentException When the current node is empty
623+
*/
624624
public function outerHtml(): string
625625
{
626626
if (!\count($this)) {
@@ -642,6 +642,8 @@ public function outerHtml(): string
642642
*
643643
* Since an XPath expression might evaluate to either a simple type or a \DOMNodeList,
644644
* this method will return either an array of simple types or a new Crawler instance.
645+
*
646+
* @return array|static
645647
*/
646648
public function evaluate(string $xpath): array|self
647649
{
@@ -1078,7 +1080,7 @@ private function supportsEncoding(string $encoding): bool
10781080
{
10791081
try {
10801082
return '' === @mb_convert_encoding('', $encoding, 'UTF-8');
1081-
} catch (\Throwable $e) {
1083+
} catch (\Throwable) {
10821084
return false;
10831085
}
10841086
}
@@ -1178,7 +1180,7 @@ private function discoverNamespace(\DOMXPath $domxpath, string $prefix): ?string
11781180
// ask for one namespace, otherwise we'd get a collection with an item for each node
11791181
$namespaces = $domxpath->query(\sprintf('(//namespace::*[name()="%s"])[last()]', $this->defaultNamespacePrefix === $prefix ? '' : $prefix));
11801182

1181-
return $this->cachedNamespaces[$prefix] = ($node = $namespaces->item(0)) ? $node->nodeValue : null;
1183+
return $this->cachedNamespaces[$prefix] = $namespaces->item(0)?->nodeValue;
11821184
}
11831185

11841186
private function findNamespacePrefixes(string $xpath): array
@@ -1193,7 +1195,7 @@ private function findNamespacePrefixes(string $xpath): array
11931195
/**
11941196
* Creates a crawler for some subnodes.
11951197
*
1196-
* @param \DOMNodeList|\DOMNode|\DOMNode[]|string|null $nodes
1198+
* @param \DOMNodeList<\DOMNode>|\DOMNode|\DOMNode[]|string|null $nodes
11971199
*/
11981200
private function createSubCrawler(\DOMNodeList|\DOMNode|array|string|null $nodes): static
11991201
{

0 commit comments

Comments
 (0)