From 29e97f7bd45a50cdd9d51cdb932528dfe9f7f27d Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 00:28:58 +0100 Subject: [PATCH 01/35] Add a custom node visitor which generates array shapes for parameters. --- composer.json | 1 + generate.sh | 1 + visitor.php | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 96 insertions(+) create mode 100644 visitor.php diff --git a/composer.json b/composer.json index ead6940..54bfe8f 100644 --- a/composer.json +++ b/composer.json @@ -13,6 +13,7 @@ }, "require-dev": { "php": "~7.1", + "phpdocumentor/reflection-docblock": "^5.3", "giacocorsiglia/stubs-generator": "^0.5.0" }, "suggest": { diff --git a/generate.sh b/generate.sh index c4bd635..6f87b34 100755 --- a/generate.sh +++ b/generate.sh @@ -18,6 +18,7 @@ fi "$(dirname "$0")/vendor/bin/generate-stubs" \ --force \ --finder=finder.php \ + --visitor=visitor.php \ --header="$HEADER" \ --functions \ --classes \ diff --git a/visitor.php b/visitor.php new file mode 100644 index 0000000..d9bb54e --- /dev/null +++ b/visitor.php @@ -0,0 +1,94 @@ +getDocComment(); + + if (!($docComment instanceof Doc)) { + return; + } + + $newDocComment = $this->addArrayHashNotation($docComment); + + if ($newDocComment !== null) { + $node->setDocComment($newDocComment); + } + } + + private function addArrayHashNotation(Doc $docComment): ?Doc + { + $docCommentText = $docComment->getText(); + $factory = \phpDocumentor\Reflection\DocBlockFactory::createInstance(); + + try { + $docblock = $factory->create($docCommentText); + } catch ( RuntimeException $e ) { + return null; + } catch ( InvalidArgumentException $e ) { + return null; + } + + /** @var phpDocumentor\Reflection\DocBlock\Tags\Param[] */ + $params = $docblock->getTagsByName('param'); + + if (!$params) { + return null; + } + + $additions = []; + + foreach ($params as $param) { + $paramDescription = $param->getDescription()->__toString(); + $paramVariableName = $param->getVariableName(); + $paramVariableType = $param->getType(); + + if (!$paramVariableName || !$paramVariableType || strpos($paramDescription, ' @type') === false) { + continue; + } + + $types = preg_split('/\R+ @type /', $paramDescription); + unset($types[0]); + $elements = []; + + foreach ($types as $type) { + $parts = preg_split('#\s+#', $type); + $elements[] = substr($parts[1], 1) . '?: ' . $parts[0]; + } + + $additions[] = sprintf( + " * @phpstan-param %1\$s{\n * %2\$s,\n * } $%3\$s", + str_replace(['|string', 'string|'], '', $paramVariableType->__toString()), + implode(",\n * ", $elements), + $paramVariableName + ); + } + + if (!$additions) { + return null; + } + + $newDocComment = sprintf( + "%s\n%s\n */", + substr($docCommentText,0,-4), + implode("\n", $additions) + ); + + return new Doc($newDocComment, $docComment->getLine(), $docComment->getFilePos()); + } +}; From 30c59aa923596071142c075a7a1e69c3772b231b Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 00:41:02 +0100 Subject: [PATCH 02/35] Don't generate an array shape if any of its elements keys are unknown. --- visitor.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/visitor.php b/visitor.php index d9bb54e..b7c9e15 100644 --- a/visitor.php +++ b/visitor.php @@ -68,6 +68,11 @@ private function addArrayHashNotation(Doc $docComment): ?Doc foreach ($types as $type) { $parts = preg_split('#\s+#', $type); + + if (strpos($parts[1], '...$') !== false) { + return null; + } + $elements[] = substr($parts[1], 1) . '?: ' . $parts[0]; } From dede957f19a93e2a62fb090458ba1c2c19a1282b Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 01:07:01 +0100 Subject: [PATCH 03/35] Handle more wonky spacing. --- visitor.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index b7c9e15..3b8214c 100644 --- a/visitor.php +++ b/visitor.php @@ -67,7 +67,7 @@ private function addArrayHashNotation(Doc $docComment): ?Doc $elements = []; foreach ($types as $type) { - $parts = preg_split('#\s+#', $type); + $parts = preg_split('#\s+#', trim($type)); if (strpos($parts[1], '...$') !== false) { return null; From 67bba4ccfd2ba3395addf3702ff61801ae80f4cb Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 01:13:04 +0100 Subject: [PATCH 04/35] Make this easier to read. --- visitor.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/visitor.php b/visitor.php index 3b8214c..b48eba4 100644 --- a/visitor.php +++ b/visitor.php @@ -66,14 +66,14 @@ private function addArrayHashNotation(Doc $docComment): ?Doc unset($types[0]); $elements = []; - foreach ($types as $type) { - $parts = preg_split('#\s+#', trim($type)); + foreach ($types as $typeTag) { + list($type, $name) = preg_split('#\s+#', trim($typeTag)); - if (strpos($parts[1], '...$') !== false) { + if (strpos($name, '...$') !== false) { return null; } - $elements[] = substr($parts[1], 1) . '?: ' . $parts[0]; + $elements[] = substr($name, 1) . '?: ' . $type; } $additions[] = sprintf( From 555e8f60a07c5dc9466c3c556f4bbe9f6e60e33d Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 01:19:49 +0100 Subject: [PATCH 05/35] PHPStan doesn't allow typed shaped arrays. --- visitor.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index b48eba4..388a666 100644 --- a/visitor.php +++ b/visitor.php @@ -76,9 +76,11 @@ private function addArrayHashNotation(Doc $docComment): ?Doc $elements[] = substr($name, 1) . '?: ' . $type; } + $paramVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $paramVariableType->__toString()); + $additions[] = sprintf( " * @phpstan-param %1\$s{\n * %2\$s,\n * } $%3\$s", - str_replace(['|string', 'string|'], '', $paramVariableType->__toString()), + str_replace(['|string', 'string|'], '', $paramVariableType), implode(",\n * ", $elements), $paramVariableName ); From 722310ff7fa06b11b0cc94ec652d190b41b4014d Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 01:29:30 +0100 Subject: [PATCH 06/35] Don't use an array shape if it's not an array. --- visitor.php | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/visitor.php b/visitor.php index 388a666..fd203a3 100644 --- a/visitor.php +++ b/visitor.php @@ -66,6 +66,12 @@ private function addArrayHashNotation(Doc $docComment): ?Doc unset($types[0]); $elements = []; + $paramVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $paramVariableType->__toString()); + + if (strpos($paramVariableType, 'array') === false) { + continue; + } + foreach ($types as $typeTag) { list($type, $name) = preg_split('#\s+#', trim($typeTag)); @@ -76,8 +82,6 @@ private function addArrayHashNotation(Doc $docComment): ?Doc $elements[] = substr($name, 1) . '?: ' . $type; } - $paramVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $paramVariableType->__toString()); - $additions[] = sprintf( " * @phpstan-param %1\$s{\n * %2\$s,\n * } $%3\$s", str_replace(['|string', 'string|'], '', $paramVariableType), From fee75f8e5e2ff1d1ad53d83a14fad1deb0360272 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 01:33:11 +0100 Subject: [PATCH 07/35] Push the array type to the end of the list. --- visitor.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/visitor.php b/visitor.php index fd203a3..ffcd0a8 100644 --- a/visitor.php +++ b/visitor.php @@ -72,6 +72,10 @@ private function addArrayHashNotation(Doc $docComment): ?Doc continue; } + if (strpos($paramVariableType, 'array|') !== false) { + $paramVariableType = str_replace('array|', '', $paramVariableType) . '|array'; + } + foreach ($types as $typeTag) { list($type, $name) = preg_split('#\s+#', trim($typeTag)); From fb0d9f1cec48a2c28f8dfab567a8fe482352f2f5 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 01:38:25 +0100 Subject: [PATCH 08/35] Ignore broken parameter references. --- visitor.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/visitor.php b/visitor.php index ffcd0a8..5bd2a6d 100644 --- a/visitor.php +++ b/visitor.php @@ -83,6 +83,10 @@ private function addArrayHashNotation(Doc $docComment): ?Doc return null; } + if (strpos($name, '$') !== 0) { + return null; + } + $elements[] = substr($name, 1) . '?: ' . $type; } From 49b5e0e349645b2fbfc54dd31d249100d2f58353 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 02:17:20 +0100 Subject: [PATCH 09/35] Coding standards. --- visitor.php | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/visitor.php b/visitor.php index 5bd2a6d..3a85c2a 100644 --- a/visitor.php +++ b/visitor.php @@ -38,9 +38,9 @@ private function addArrayHashNotation(Doc $docComment): ?Doc try { $docblock = $factory->create($docCommentText); - } catch ( RuntimeException $e ) { + } catch ( \RuntimeException $e ) { return null; - } catch ( InvalidArgumentException $e ) { + } catch ( \InvalidArgumentException $e ) { return null; } @@ -104,7 +104,7 @@ private function addArrayHashNotation(Doc $docComment): ?Doc $newDocComment = sprintf( "%s\n%s\n */", - substr($docCommentText,0,-4), + substr($docCommentText, 0, -4), implode("\n", $additions) ); From bb213a103884f2827d5f3084900ff384b23cfeae Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 02:17:34 +0100 Subject: [PATCH 10/35] Reuse the docblock factory. --- visitor.php | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/visitor.php b/visitor.php index 3a85c2a..8fa2c77 100644 --- a/visitor.php +++ b/visitor.php @@ -10,6 +10,13 @@ return new class extends NodeVisitor { + private \phpDocumentor\Reflection\DocBlockFactory $docBlockFactory; + + public function __construct() + { + $this->docBlockFactory = \phpDocumentor\Reflection\DocBlockFactory::createInstance(); + } + public function enterNode(Node $node) { parent::enterNode($node); @@ -34,10 +41,9 @@ public function enterNode(Node $node) private function addArrayHashNotation(Doc $docComment): ?Doc { $docCommentText = $docComment->getText(); - $factory = \phpDocumentor\Reflection\DocBlockFactory::createInstance(); try { - $docblock = $factory->create($docCommentText); + $docblock = $this->docBlockFactory->create($docCommentText); } catch ( \RuntimeException $e ) { return null; } catch ( \InvalidArgumentException $e ) { From e557e53485128c2b7b76ce4b0eddcd29016f8e4f Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 30 Nov 2021 11:01:55 +0100 Subject: [PATCH 11/35] PHPStan config. --- composer.json | 1 + phpstan.neon | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 phpstan.neon diff --git a/composer.json b/composer.json index 54bfe8f..58d54f2 100644 --- a/composer.json +++ b/composer.json @@ -14,6 +14,7 @@ "require-dev": { "php": "~7.1", "phpdocumentor/reflection-docblock": "^5.3", + "phpstan/phpstan": "^1.2", "giacocorsiglia/stubs-generator": "^0.5.0" }, "suggest": { diff --git a/phpstan.neon b/phpstan.neon new file mode 100644 index 0000000..86040aa --- /dev/null +++ b/phpstan.neon @@ -0,0 +1,17 @@ +parameters: + level: 2 + paths: + - wordpress-stubs.php + ignoreErrors: + - '#return statement is missing#' + - '#PHPMailer#' + - '#duplicate keys with value#' + - '#WP_HTTP_Streams#' + - '#unused parameter#' + - '#Constant [A-Z0-9_]+ not found#' + - '#Default value of the parameter#' + - '#\stream#' + - '#\GdImage#' + - '#\IRI#' + - '#Requests#' + - '#SimplePie#' From b598e905f41a7dd0bcf98f181cbcc340dc1430d2 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Wed, 1 Dec 2021 01:27:22 +0100 Subject: [PATCH 12/35] Docs. --- visitor.php | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index 8fa2c77..02d4f1f 100644 --- a/visitor.php +++ b/visitor.php @@ -64,31 +64,45 @@ private function addArrayHashNotation(Doc $docComment): ?Doc $paramVariableName = $param->getVariableName(); $paramVariableType = $param->getType(); - if (!$paramVariableName || !$paramVariableType || strpos($paramDescription, ' @type') === false) { + // Skip if the parameter variable name or type are missing. + if (!$paramVariableName || !$paramVariableType) { continue; } + // Skip if the description doesn't contain at least one correctly + // formatted `@type`, which indicates an array hash. + if (strpos($paramDescription, ' @type') === false) { + continue; + } + + // Populate `$types` with the value of each top level `@type`. $types = preg_split('/\R+ @type /', $paramDescription); unset($types[0]); $elements = []; + // PHPStan dosn't support typed array shapes (`int[]{...}`) so replace + // typed arrays such as `int[]` with `array`. $paramVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $paramVariableType->__toString()); if (strpos($paramVariableType, 'array') === false) { + // Skip if we have hash notation that's not for an array (ie. for `object`). continue; } if (strpos($paramVariableType, 'array|') !== false) { + // Move `array` to the end of union types so the appended array shape works. $paramVariableType = str_replace('array|', '', $paramVariableType) . '|array'; } foreach ($types as $typeTag) { list($type, $name) = preg_split('#\s+#', trim($typeTag)); + // Bail out completely if any element doesn't have a static key. if (strpos($name, '...$') !== false) { return null; } + // Bail out completely if the name of any element is invalid. if (strpos($name, '$') !== 0) { return null; } From 14489d55911f6aa68b1421f4dc03b6b852eaf553 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Wed, 1 Dec 2021 01:31:02 +0100 Subject: [PATCH 13/35] Fix these. --- phpstan.neon | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/phpstan.neon b/phpstan.neon index 86040aa..075aea3 100644 --- a/phpstan.neon +++ b/phpstan.neon @@ -10,8 +10,8 @@ parameters: - '#unused parameter#' - '#Constant [A-Z0-9_]+ not found#' - '#Default value of the parameter#' - - '#\stream#' - - '#\GdImage#' - - '#\IRI#' + - '#\\stream#' + - '#\\GdImage#' + - '#\\IRI#' - '#Requests#' - '#SimplePie#' From 04206ad5d84f7d39247988e528a9010905a8f962 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 21:48:14 +0100 Subject: [PATCH 14/35] Split this up a bit. --- visitor.php | 116 ++++++++++++++++++++++++++++------------------------ 1 file changed, 63 insertions(+), 53 deletions(-) diff --git a/visitor.php b/visitor.php index 02d4f1f..59d0d66 100644 --- a/visitor.php +++ b/visitor.php @@ -2,6 +2,7 @@ declare(strict_types = 1); +use phpDocumentor\Reflection\DocBlock\Tags\Param; use PhpParser\Comment\Doc; use PhpParser\Node; use PhpParser\Node\Stmt\ClassMethod; @@ -50,7 +51,7 @@ private function addArrayHashNotation(Doc $docComment): ?Doc return null; } - /** @var phpDocumentor\Reflection\DocBlock\Tags\Param[] */ + /** @var \phpDocumentor\Reflection\DocBlock\Tags\Param[] */ $params = $docblock->getTagsByName('param'); if (!$params) { @@ -60,74 +61,83 @@ private function addArrayHashNotation(Doc $docComment): ?Doc $additions = []; foreach ($params as $param) { - $paramDescription = $param->getDescription()->__toString(); - $paramVariableName = $param->getVariableName(); - $paramVariableType = $param->getType(); + $addition = $this->getAdditionFromParam($param); - // Skip if the parameter variable name or type are missing. - if (!$paramVariableName || !$paramVariableType) { - continue; + if ($addition !== null) { + $additions[] = $addition; } + } - // Skip if the description doesn't contain at least one correctly - // formatted `@type`, which indicates an array hash. - if (strpos($paramDescription, ' @type') === false) { - continue; - } + if (!$additions) { + return null; + } - // Populate `$types` with the value of each top level `@type`. - $types = preg_split('/\R+ @type /', $paramDescription); - unset($types[0]); - $elements = []; + $newDocComment = sprintf( + "%s\n%s\n */", + substr($docCommentText, 0, -4), + implode("\n", $additions) + ); - // PHPStan dosn't support typed array shapes (`int[]{...}`) so replace - // typed arrays such as `int[]` with `array`. - $paramVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $paramVariableType->__toString()); + return new Doc($newDocComment, $docComment->getLine(), $docComment->getFilePos()); + } - if (strpos($paramVariableType, 'array') === false) { - // Skip if we have hash notation that's not for an array (ie. for `object`). - continue; - } + private function getAdditionFromParam(Param $param): ?string + { + $paramDescription = $param->getDescription()->__toString(); + $paramVariableName = $param->getVariableName(); + $paramVariableType = $param->getType(); - if (strpos($paramVariableType, 'array|') !== false) { - // Move `array` to the end of union types so the appended array shape works. - $paramVariableType = str_replace('array|', '', $paramVariableType) . '|array'; - } + // Skip if the parameter variable name or type are missing. + if (!$paramVariableName || !$paramVariableType) { + return null; + } - foreach ($types as $typeTag) { - list($type, $name) = preg_split('#\s+#', trim($typeTag)); + // Skip if the description doesn't contain at least one correctly + // formatted `@type`, which indicates an array hash. + if (strpos($paramDescription, ' @type') === false) { + return null; + } - // Bail out completely if any element doesn't have a static key. - if (strpos($name, '...$') !== false) { - return null; - } + // Populate `$types` with the value of each top level `@type`. + $types = preg_split('/\R+ @type /', $paramDescription); + unset($types[0]); + $elements = []; - // Bail out completely if the name of any element is invalid. - if (strpos($name, '$') !== 0) { - return null; - } + // PHPStan dosn't support typed array shapes (`int[]{...}`) so replace + // typed arrays such as `int[]` with `array`. + $paramVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $paramVariableType->__toString()); - $elements[] = substr($name, 1) . '?: ' . $type; - } + if (strpos($paramVariableType, 'array') === false) { + // Skip if we have hash notation that's not for an array (ie. for `object`). + return null; + } - $additions[] = sprintf( - " * @phpstan-param %1\$s{\n * %2\$s,\n * } $%3\$s", - str_replace(['|string', 'string|'], '', $paramVariableType), - implode(",\n * ", $elements), - $paramVariableName - ); + if (strpos($paramVariableType, 'array|') !== false) { + // Move `array` to the end of union types so the appended array shape works. + $paramVariableType = str_replace('array|', '', $paramVariableType) . '|array'; } - if (!$additions) { - return null; + foreach ($types as $typeTag) { + list($type, $name) = preg_split('#\s+#', trim($typeTag)); + + // Bail out completely if any element doesn't have a static key. + if (strpos($name, '...$') !== false) { + return null; + } + + // Bail out completely if the name of any element is invalid. + if (strpos($name, '$') !== 0) { + return null; + } + + $elements[] = substr($name, 1) . '?: ' . $type; } - $newDocComment = sprintf( - "%s\n%s\n */", - substr($docCommentText, 0, -4), - implode("\n", $additions) + return sprintf( + " * @phpstan-param %1\$s{\n * %2\$s,\n * } $%3\$s", + str_replace(['|string', 'string|'], '', $paramVariableType), + implode(",\n * ", $elements), + $paramVariableName ); - - return new Doc($newDocComment, $docComment->getLine(), $docComment->getFilePos()); } }; From b78ffe33abb52fbcdf14b9507e5a7c280f612d12 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 22:06:41 +0100 Subject: [PATCH 15/35] Prepare this to be applicable to any tag type. --- visitor.php | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/visitor.php b/visitor.php index 59d0d66..2c0fa1d 100644 --- a/visitor.php +++ b/visitor.php @@ -81,40 +81,40 @@ private function addArrayHashNotation(Doc $docComment): ?Doc return new Doc($newDocComment, $docComment->getLine(), $docComment->getFilePos()); } - private function getAdditionFromParam(Param $param): ?string + private function getAdditionFromParam(Param $tag): ?string { - $paramDescription = $param->getDescription()->__toString(); - $paramVariableName = $param->getVariableName(); - $paramVariableType = $param->getType(); + $tagDescription = $tag->getDescription()->__toString(); + $tagVariableName = $tag->getVariableName(); + $tagVariableType = $tag->getType(); // Skip if the parameter variable name or type are missing. - if (!$paramVariableName || !$paramVariableType) { + if (!$tagVariableName || !$tagVariableType) { return null; } // Skip if the description doesn't contain at least one correctly // formatted `@type`, which indicates an array hash. - if (strpos($paramDescription, ' @type') === false) { + if (strpos($tagDescription, ' @type') === false) { return null; } // Populate `$types` with the value of each top level `@type`. - $types = preg_split('/\R+ @type /', $paramDescription); + $types = preg_split('/\R+ @type /', $tagDescription); unset($types[0]); $elements = []; // PHPStan dosn't support typed array shapes (`int[]{...}`) so replace // typed arrays such as `int[]` with `array`. - $paramVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $paramVariableType->__toString()); + $tagVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $tagVariableType->__toString()); - if (strpos($paramVariableType, 'array') === false) { + if (strpos($tagVariableType, 'array') === false) { // Skip if we have hash notation that's not for an array (ie. for `object`). return null; } - if (strpos($paramVariableType, 'array|') !== false) { + if (strpos($tagVariableType, 'array|') !== false) { // Move `array` to the end of union types so the appended array shape works. - $paramVariableType = str_replace('array|', '', $paramVariableType) . '|array'; + $tagVariableType = str_replace('array|', '', $tagVariableType) . '|array'; } foreach ($types as $typeTag) { @@ -135,9 +135,9 @@ private function getAdditionFromParam(Param $param): ?string return sprintf( " * @phpstan-param %1\$s{\n * %2\$s,\n * } $%3\$s", - str_replace(['|string', 'string|'], '', $paramVariableType), + str_replace(['|string', 'string|'], '', $tagVariableType), implode(",\n * ", $elements), - $paramVariableName + $tagVariableName ); } }; From 29fc893edb1f201f02a7fdcd059e987a0a08b115 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 22:21:07 +0100 Subject: [PATCH 16/35] More splitting up. --- visitor.php | 48 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 13 deletions(-) diff --git a/visitor.php b/visitor.php index 2c0fa1d..33b75d6 100644 --- a/visitor.php +++ b/visitor.php @@ -87,22 +87,39 @@ private function getAdditionFromParam(Param $tag): ?string $tagVariableName = $tag->getVariableName(); $tagVariableType = $tag->getType(); + // Skip if the description doesn't contain at least one correctly + // formatted `@type`, which indicates an array hash. + if (strpos($tagDescription, ' @type') === false) { + return null; + } + // Skip if the parameter variable name or type are missing. if (!$tagVariableName || !$tagVariableType) { return null; } - // Skip if the description doesn't contain at least one correctly - // formatted `@type`, which indicates an array hash. - if (strpos($tagDescription, ' @type') === false) { + $tagVariableType = $this->getTypeFromTag($tagVariableType); + + if ($tagVariableType === null) { return null; } - // Populate `$types` with the value of each top level `@type`. - $types = preg_split('/\R+ @type /', $tagDescription); - unset($types[0]); - $elements = []; + $elements = $this->getElementsFromTag($tagDescription); + + if ($elements === null) { + return null; + } + + return sprintf( + " * @phpstan-param %1\$s{\n * %2\$s,\n * } $%3\$s", + str_replace(['|string', 'string|'], '', $tagVariableType), + implode(",\n * ", $elements), + $tagVariableName + ); + } + private function getTypeFromTag(Type $tagVariableType): ?string + { // PHPStan dosn't support typed array shapes (`int[]{...}`) so replace // typed arrays such as `int[]` with `array`. $tagVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $tagVariableType->__toString()); @@ -117,6 +134,16 @@ private function getAdditionFromParam(Param $tag): ?string $tagVariableType = str_replace('array|', '', $tagVariableType) . '|array'; } + return $tagVariableType; + } + + private function getElementsFromTag(string $tagDescription): ?array + { + // Populate `$types` with the value of each top level `@type`. + $types = preg_split('/\R+ @type /', $tagDescription); + unset($types[0]); + $elements = []; + foreach ($types as $typeTag) { list($type, $name) = preg_split('#\s+#', trim($typeTag)); @@ -133,11 +160,6 @@ private function getAdditionFromParam(Param $tag): ?string $elements[] = substr($name, 1) . '?: ' . $type; } - return sprintf( - " * @phpstan-param %1\$s{\n * %2\$s,\n * } $%3\$s", - str_replace(['|string', 'string|'], '', $tagVariableType), - implode(",\n * ", $elements), - $tagVariableName - ); + return $elements; } }; From c7698d207c2568bd80198461dcf7ff7cfeb63b96 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 22:25:18 +0100 Subject: [PATCH 17/35] Generate `@phpstan-return` tags too. --- visitor.php | 50 +- wordpress-stubs.php | 2110 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 2159 insertions(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index 33b75d6..5c51733 100644 --- a/visitor.php +++ b/visitor.php @@ -3,6 +3,8 @@ declare(strict_types = 1); use phpDocumentor\Reflection\DocBlock\Tags\Param; +use phpDocumentor\Reflection\DocBlock\Tags\Return_; +use phpDocumentor\Reflection\Type; use PhpParser\Comment\Doc; use PhpParser\Node; use PhpParser\Node\Stmt\ClassMethod; @@ -54,7 +56,10 @@ private function addArrayHashNotation(Doc $docComment): ?Doc /** @var \phpDocumentor\Reflection\DocBlock\Tags\Param[] */ $params = $docblock->getTagsByName('param'); - if (!$params) { + /** @var \phpDocumentor\Reflection\DocBlock\Tags\Return_[] */ + $returns = $docblock->getTagsByName('return'); + + if (!$params && !$returns) { return null; } @@ -68,6 +73,14 @@ private function addArrayHashNotation(Doc $docComment): ?Doc } } + if ($returns) { + $addition = $this->getAdditionFromReturn($returns[0]); + + if ($addition !== null) { + $additions[] = $addition; + } + } + if (!$additions) { return null; } @@ -118,6 +131,41 @@ private function getAdditionFromParam(Param $tag): ?string ); } + private function getAdditionFromReturn(Return_ $tag): ?string + { + $tagDescription = $tag->getDescription()->__toString(); + $tagVariableType = $tag->getType(); + + // Skip if the description doesn't contain at least one correctly + // formatted `@type`, which indicates an array hash. + if (strpos($tagDescription, ' @type') === false) { + return null; + } + + // Skip if the return type is missing. + if (!$tagVariableType) { + return null; + } + + $tagVariableType = $this->getTypeFromTag($tagVariableType); + + if ($tagVariableType === null) { + return null; + } + + $elements = $this->getElementsFromTag($tagDescription); + + if ($elements === null) { + return null; + } + + return sprintf( + " * @phpstan-return %1\$s{\n * %2\$s,\n * }", + str_replace(['|string', 'string|'], '', $tagVariableType), + implode(",\n * ", $elements) + ); + } + private function getTypeFromTag(Type $tagVariableType): ?string { // PHPStan dosn't support typed array shapes (`int[]{...}`) so replace diff --git a/wordpress-stubs.php b/wordpress-stubs.php index f2ec948..a5632e2 100644 --- a/wordpress-stubs.php +++ b/wordpress-stubs.php @@ -640,6 +640,14 @@ public function clear_destination($remote_destination) * } * * @return array|WP_Error The result (also stored in `WP_Upgrader::$result`), or a WP_Error on failure. + * @phpstan-param array{ + * source?: string, + * destination?: string, + * clear_destination?: bool, + * clear_working?: bool, + * abort_if_destination_exists?: bool, + * hook_extra?: array, + * } $args */ public function install_package($args = array()) { @@ -676,6 +684,15 @@ public function install_package($args = array()) * } * @return array|false|WP_Error The result from self::install_package() on success, otherwise a WP_Error, * or false if unable to connect to the filesystem. + * @phpstan-param array{ + * package?: string, + * destination?: string, + * clear_destination?: bool, + * clear_working?: bool, + * abort_if_destination_exists?: bool, + * is_multi?: bool, + * hook_extra?: array, + * } $options */ public function run($options) { @@ -769,6 +786,11 @@ public function upgrade_strings() * Default false. * } * @return string|false|WP_Error New WordPress version on success, false or WP_Error on failure. + * @phpstan-param array{ + * pre_check_md5?: bool, + * attempt_rollback?: bool, + * do_rollback?: bool, + * } $args */ public function upgrade($current, $args = array()) { @@ -1810,6 +1832,9 @@ public function upgrade($update = \false, $args = array()) * } * @return array|bool|WP_Error Will return an array of results, or true if there are no updates, * false or WP_Error for initial errors. + * @phpstan-param array{ + * clear_update_cache?: bool, + * } $args */ public function bulk_upgrade($language_updates = array(), $args = array()) { @@ -2856,6 +2881,9 @@ public function install_strings() * Default true. * } * @return bool|WP_Error True if the installation was successful, false or a WP_Error otherwise. + * @phpstan-param array{ + * clear_update_cache?: bool, + * } $args */ public function install($package, $args = array()) { @@ -2874,6 +2902,9 @@ public function install($package, $args = array()) * Default true. * } * @return bool|WP_Error True if the upgrade was successful, false or a WP_Error object otherwise. + * @phpstan-param array{ + * clear_update_cache?: bool, + * } $args */ public function upgrade($plugin, $args = array()) { @@ -2891,6 +2922,9 @@ public function upgrade($plugin, $args = array()) * @type bool $clear_update_cache Whether to clear the plugin updates cache if successful. Default true. * } * @return array|false An array of results indexed by plugin file, or false if unable to connect to the filesystem. + * @phpstan-param array{ + * clear_update_cache?: bool, + * } $args */ public function bulk_upgrade($plugins, $args = array()) { @@ -3205,6 +3239,9 @@ public function hide_activate_preview_actions($actions) * } * * @return bool|WP_Error True if the installation was successful, false or a WP_Error object otherwise. + * @phpstan-param array{ + * clear_update_cache?: bool, + * } $args */ public function install($package, $args = array()) { @@ -3223,6 +3260,9 @@ public function install($package, $args = array()) * Default true. * } * @return bool|WP_Error True if the upgrade was successful, false or a WP_Error object otherwise. + * @phpstan-param array{ + * clear_update_cache?: bool, + * } $args */ public function upgrade($theme, $args = array()) { @@ -3241,6 +3281,9 @@ public function upgrade($theme, $args = array()) * Default true. * } * @return array[]|false An array of results, or false if unable to connect to the filesystem. + * @phpstan-param array{ + * clear_update_cache?: bool, + * } $args */ public function bulk_upgrade($themes, $args = array()) { @@ -4029,6 +4072,12 @@ class WP_List_Table * screen. If left null, the current screen will be automatically set. * Default null. * } + * @phpstan-param array{ + * plural?: string, + * singular?: string, + * ajax?: bool, + * screen?: string, + * } $args */ public function __construct($args = array()) { @@ -5072,6 +5121,12 @@ class WP_Community_Events * symbol. e.g.: -122.341100. * @type string $country The ISO 3166-1 alpha-2 country code. e.g.: BR * } + * @phpstan-param false|array{ + * description?: string, + * latitude?: string, + * longitude?: string, + * country?: string, + * } $user_location */ public function __construct($user_id, $user_location = \false) { @@ -5897,6 +5952,7 @@ public function rmdir($path, $recursive = \false) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } + * boop */ public function dirlist($path, $include_hidden = \true, $recursive = \false) { @@ -6266,6 +6322,7 @@ public function rmdir($path, $recursive = \false) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } + * boop */ public function dirlist($path, $include_hidden = \true, $recursive = \false) { @@ -6628,6 +6685,7 @@ public function parselisting($line) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } + * boop */ public function dirlist($path = '.', $include_hidden = \true, $recursive = \false) { @@ -6991,6 +7049,7 @@ public function rmdir($path, $recursive = \false) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } + * boop */ public function dirlist($path = '.', $include_hidden = \true, $recursive = \false) { @@ -7439,6 +7498,7 @@ public function rmdir($path, $recursive = \false) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } + * boop */ public function dirlist($path, $include_hidden = \true, $recursive = \false) { @@ -10238,6 +10298,13 @@ public function get_help_tab($id) * @type callable $callback Optional. A callback to generate the tab content. Default false. * @type int $priority Optional. The priority of the tab, used for ordering. Default 10. * } + * @phpstan-param array{ + * title?: string, + * id?: string, + * content?: string, + * callback?: callable, + * priority?: int, + * } $args */ public function add_help_tab($args) { @@ -10337,6 +10404,11 @@ public function get_screen_reader_text($key) * @type string $heading_list Screen reader text for the items list heading. * Default 'Items list'. * } + * @phpstan-param array{ + * heading_views?: string, + * heading_pagination?: string, + * heading_list?: string, + * } $content */ public function set_screen_reader_content($content = array()) { @@ -10379,6 +10451,9 @@ public function show_screen_options() * * @type bool $wrap Whether the screen-options-wrap div will be included. Defaults to true. * } + * @phpstan-param array{ + * wrap?: bool, + * } $options */ public function render_screen_options($options = array()) { @@ -29143,6 +29218,25 @@ class WP_Http * } * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. * A WP_Error instance upon error. + * @phpstan-param array{ + * method?: string, + * timeout?: float, + * redirection?: int, + * httpversion?: string, + * user-agent?: string, + * reject_unsafe_urls?: bool, + * blocking?: bool, + * headers?: string|array, + * cookies?: array, + * body?: string|array, + * compress?: bool, + * decompress?: bool, + * sslverify?: bool, + * sslcertificates?: string, + * stream?: bool, + * filename?: string, + * limit_response_size?: int, + * } $args */ public function request($url, $args = array()) { @@ -29277,6 +29371,7 @@ public function head($url, $args = array()) * @type string $headers HTTP response headers. * @type string $body HTTP response body. * } + * boop */ public static function processResponse($strResponse) { @@ -29303,6 +29398,7 @@ public static function processResponse($strResponse) * @type WP_Http_Cookie[] $cookies If the original headers contain the 'Set-Cookie' key, * an array containing `WP_Http_Cookie` objects is returned. * } + * boop */ public static function processHeaders($headers, $url = '') { @@ -30639,6 +30735,14 @@ public function remove_menu($id) * @type array $meta Meta data including the following keys: 'html', 'class', 'rel', 'lang', 'dir', * 'onclick', 'target', 'title', 'tabindex'. Default empty. * } + * @phpstan-param array{ + * id?: string, + * title?: string, + * parent?: string, + * href?: string, + * group?: bool, + * meta?: array, + * } $args */ public function add_node($args) { @@ -30692,6 +30796,11 @@ protected final function _get_nodes() * @type array $meta Meta data for the group including the following keys: * 'class', 'onclick', 'target', and 'title'. * } + * @phpstan-param array{ + * id?: string, + * parent?: string, + * meta?: array, + * } $args */ public final function add_group($args) { @@ -30825,6 +30934,15 @@ public function __construct($args = '') * element as CDATA. Default empty array. * } * @return string XML response. + * @phpstan-param array{ + * what?: string, + * action?: string|false, + * id?: int|WP_Error, + * old_id?: int|false, + * position?: string, + * data?: string|WP_Error, + * supplemental?: array, + * } $args */ public function add($args = '') { @@ -32297,6 +32415,28 @@ class WP_Block_Type * @type string|null $editor_style Block type editor style handle. * @type string|null $style Block type front end style handle. * } + * @phpstan-param array{ + * api_version?: string, + * title?: string, + * category?: string|null, + * parent?: array|null, + * icon?: string|null, + * description?: string, + * keywords?: array, + * textdomain?: string|null, + * styles?: array, + * variations?: array, + * supports?: array|null, + * example?: array|null, + * render_callback?: callable|null, + * attributes?: array|null, + * uses_context?: array, + * provides_context?: array|null, + * editor_script?: string|null, + * script?: string|null, + * editor_style?: string|null, + * style?: string|null, + * } $args */ public function __construct($block_type, $args = array()) { @@ -32720,6 +32860,53 @@ public function __call($name, $arguments) * @type bool $update_comment_post_cache Whether to prime the cache for comment posts. * Default false. * } + * @phpstan-param array{ + * author_email?: string, + * author_url?: string, + * author__in?: int[], + * author__not_in?: int[], + * comment__in?: int[], + * comment__not_in?: int[], + * count?: bool, + * date_query?: array, + * fields?: string, + * ID?: int, + * include_unapproved?: array, + * karma?: int, + * meta_key?: string, + * meta_value?: string, + * meta_query?: array, + * number?: int, + * paged?: int, + * offset?: int, + * no_found_rows?: bool, + * orderby?: string|array, + * order?: string, + * parent?: int, + * parent__in?: int[], + * parent__not_in?: int[], + * post_author__in?: int[], + * post_author__not_in?: int[], + * post_ID?: int, + * post_id?: int, + * post__in?: int[], + * post__not_in?: int[], + * post_author?: int, + * post_status?: string|array, + * post_type?: string, + * post_name?: string, + * post_parent?: int, + * search?: string, + * status?: string|array, + * type?: string|array, + * type__in?: string[], + * type__not_in?: string[], + * user_id?: int, + * hierarchical?: bool|string, + * cache_domain?: string, + * update_comment_meta_cache?: bool, + * update_comment_post_cache?: bool, + * } $query */ public function __construct($query = '') { @@ -33061,6 +33248,12 @@ public function to_array() * 'none' to disable `ORDER BY` clause. * } * @return WP_Comment[] Array of `WP_Comment` objects. + * @phpstan-param array{ + * format?: string, + * status?: string, + * hierarchical?: string, + * orderby?: string|array, + * } $args */ public function get_children($args = array()) { @@ -33317,6 +33510,24 @@ class WP_Customize_Control * 'date' are supported implicitly. Default 'text'. * @type callable $active_callback Active callback. * } + * @phpstan-param array{ + * instance_number?: int, + * manager?: WP_Customize_Manager, + * id?: string, + * settings?: array, + * setting?: string, + * capability?: string, + * priority?: int, + * section?: string, + * label?: string, + * description?: string, + * choices?: array, + * input_attrs?: array, + * allow_addition?: bool, + * json?: array, + * type?: string, + * active_callback?: callable, + * } $args */ public function __construct($manager, $id, $args = array()) { @@ -33730,6 +33941,14 @@ final class WP_Customize_Manager * @type bool $branching If changeset branching is allowed; otherwise, changesets are linear. Defaults to true. * @type bool $autosaved If data from a changeset's autosaved revision should be loaded if it exists. Defaults to false. * } + * @phpstan-param array{ + * changeset_uuid?: null|string|false, + * theme?: string, + * messenger_channel?: string, + * settings_previewed?: bool, + * branching?: bool, + * autosaved?: bool, + * } $args */ public function __construct($args = array()) { @@ -33990,6 +34209,12 @@ public function find_changeset_post_id($uuid) * @type bool $exclude_restore_dismissed Whether to exclude changeset auto-drafts that have been dismissed. Defaults to true. * } * @return WP_Post[] Auto-draft changesets. + * @phpstan-param array{ + * posts_per_page?: int, + * author?: int, + * post_status?: string, + * exclude_restore_dismissed?: bool, + * } $args */ protected function get_changeset_posts($args = array()) { @@ -34099,6 +34324,10 @@ public function _save_starter_content_changeset() * @type bool $exclude_post_data Whether the post input values should also be excluded. Defaults to false when lacking the customize capability. * } * @return array + * @phpstan-param array{ + * exclude_changeset?: bool, + * exclude_post_data?: bool, + * } $args */ public function unsanitized_post_values($args = array()) { @@ -34331,6 +34560,10 @@ public function current_theme($current_theme) * @type bool $validate_capability Whether the setting capability will be checked. * } * @return array Mapping of setting IDs to return value of validate method calls, either `true` or `WP_Error`. + * @phpstan-param array{ + * validate_existence?: bool, + * validate_capability?: bool, + * } $options */ public function validate_setting_values($setting_values, $options = array()) { @@ -34378,6 +34611,15 @@ public function save() * } * * @return array|WP_Error Returns array on success and WP_Error with array data on error. + * @phpstan-param array{ + * data?: array, + * status?: string, + * title?: string, + * date_gmt?: string, + * user_id?: int, + * starter_content?: bool, + * autosave?: bool, + * } $args */ function save_changeset_post($args = array()) { @@ -34993,6 +35235,11 @@ public function get_return_url() * @type string $section ID for section to be autofocused. * @type string $panel ID for panel to be autofocused. * } + * @phpstan-param array{ + * control?: string, + * section?: string, + * panel?: string, + * } $autofocus */ public function set_autofocus($autofocus) { @@ -35009,6 +35256,7 @@ public function set_autofocus($autofocus) * @type string $section ID for section to be autofocused. * @type string $panel ID for panel to be autofocused. * } + * boop */ public function get_autofocus() { @@ -35700,6 +35948,15 @@ class WP_Customize_Panel * @type string $type Type of the panel. * @type callable $active_callback Active callback. * } + * @phpstan-param array{ + * priority?: int, + * capability?: string, + * theme_supports?: string|string[], + * title?: string, + * description?: string, + * type?: string, + * active_callback?: callable, + * } $args */ public function __construct($manager, $id, $args = array()) { @@ -35980,6 +36237,17 @@ class WP_Customize_Section * instead of inline above the first control. * Default false. * } + * @phpstan-param array{ + * priority?: int, + * panel?: string, + * capability?: string, + * theme_supports?: string|string[], + * title?: string, + * description?: string, + * type?: string, + * active_callback?: callable, + * description_hidden?: bool, + * } $args */ public function __construct($manager, $id, $args = array()) { @@ -36242,6 +36510,17 @@ class WP_Customize_Setting * JSON serializable. * @type bool $dirty Whether or not the setting is initially dirty when created. * } + * @phpstan-param array{ + * type?: string, + * capability?: string, + * theme_supports?: string|string[], + * default?: string, + * transport?: string, + * validate_callback?: callable, + * sanitize_callback?: callable, + * sanitize_js_callback?: callable, + * dirty?: bool, + * } $args */ public function __construct($manager, $id, $args = array()) { @@ -36257,6 +36536,7 @@ public function __construct($manager, $id, $args = array()) * @type string $base ID base * @type array $keys Keys for multidimensional array. * } + * boop */ public final function id_data() { @@ -36975,6 +37255,7 @@ public function get_widget_control($args) * @type string $control Markup for widget control wrapping form. * @type string $content The contents of the widget form itself. * } + * boop */ public function get_widget_control_parts($args) { @@ -37251,6 +37532,10 @@ public function selective_refresh_init() * @see WP_Customize_Nav_Menus::filter_wp_nav_menu_args() * * @return array Params. + * @phpstan-param array{ + * args?: array, + * widget_args?: array, + * } $params */ public function filter_dynamic_sidebar_params($params) { @@ -37365,6 +37650,10 @@ public function filter_sidebars_widgets_for_rendering_widget($sidebars_widgets) * @type int $sidebar_instance_number Disambiguating instance number. * } * @return string|false + * @phpstan-param array{ + * sidebar_id?: string, + * sidebar_instance_number?: int, + * } $context */ public function render_widget_partial($partial, $context) { @@ -37753,6 +38042,7 @@ public function get_sql() * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ protected function get_sql_clauses() { @@ -37774,6 +38064,7 @@ protected function get_sql_clauses() * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ protected function get_sql_for_query($query, $depth = 0) { @@ -37793,6 +38084,7 @@ protected function get_sql_for_query($query, $depth = 0) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ protected function get_sql_for_subquery($query) { @@ -37810,6 +38102,7 @@ protected function get_sql_for_subquery($query) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ protected function get_sql_for_clause($query, $parent_query) { @@ -38044,6 +38337,22 @@ private function __construct() * Quicktags using an array. Default true. * } * @return array Parsed arguments array. + * @phpstan-param array{ + * wpautop?: bool, + * media_buttons?: bool, + * default_editor?: string, + * drag_drop_upload?: bool, + * textarea_name?: string, + * textarea_rows?: int, + * tabindex?: string|int, + * tabfocus_elements?: string, + * editor_css?: string, + * editor_class?: string, + * teeny?: bool, + * dfw?: bool, + * tinymce?: bool|array, + * quicktags?: bool|array, + * } $settings */ public static function parse_settings($editor_id, $settings) { @@ -38317,6 +38626,10 @@ public function unregister_handler($id, $priority = 10) * } * @param string $url The URL attempting to be embedded. * @return string|false The embed HTML on success, false otherwise. + * @phpstan-param array{ + * width?: int, + * height?: int, + * } $attr */ public function get_embed_handler_html($attr, $url) { @@ -38337,6 +38650,10 @@ public function get_embed_handler_html($attr, $url) * @param string $url The URL attempting to be embedded. * @return string|false The embed HTML on success, otherwise the original URL. * `->maybe_make_link()` can return false on failure. + * @phpstan-param array{ + * width?: int, + * height?: int, + * } $attr */ public function shortcode($attr, $url = '') { @@ -39216,6 +39533,15 @@ class WP_Http_Cookie * } * @param string $requested_url The URL which the cookie was set on, used for default $domain * and $port values. + * @phpstan-param array{ + * name?: string, + * value?: mixed, + * expires?: string|int|null, + * path?: string, + * domain?: string, + * port?: int, + * host_only?: bool, + * } $data */ public function __construct($data, $requested_url = '') { @@ -39265,6 +39591,7 @@ public function getFullHeader() * @type string $path Cookie URL path. * @type string $domain Cookie domain. * } + * boop */ public function get_attributes() { @@ -40187,6 +40514,9 @@ public abstract function resize($max_w, $max_h, $crop = \false); * } * } * @return array An array of resized images metadata by size. + * @phpstan-param array{ + * size?: array, + * } $sizes */ public abstract function multi_resize($sizes); /** @@ -40247,6 +40577,7 @@ public abstract function stream($mime_type = \null); * @type int $width The image width. * @type int $height The image height. * } + * boop */ public function get_size() { @@ -40508,6 +40839,9 @@ protected function _resize($max_w, $max_h, $crop = \false) * } * } * @return array An array of resized images' metadata by size. + * @phpstan-param array{ + * size?: array, + * } $sizes */ public function multi_resize($sizes) { @@ -40526,6 +40860,11 @@ public function multi_resize($sizes) * } * @return array|WP_Error The image data array for inclusion in the `sizes` array in the image meta, * WP_Error object on error. + * @phpstan-param array{ + * width?: int, + * height?: int, + * crop?: bool, + * } $size_data */ public function make_subsize($size_data) { @@ -40762,6 +41101,9 @@ protected function thumbnail_image($dst_w, $dst_h, $filter_name = 'FILTER_TRIANG * } * } * @return array An array of resized images' metadata by size. + * @phpstan-param array{ + * size?: array, + * } $sizes */ public function multi_resize($sizes) { @@ -40780,6 +41122,11 @@ public function multi_resize($sizes) * } * @return array|WP_Error The image data array for inclusion in the `sizes` array in the image meta, * WP_Error object on error. + * @phpstan-param array{ + * width?: int, + * height?: int, + * crop?: bool, + * } $size_data */ public function make_subsize($size_data) { @@ -41702,6 +42049,7 @@ public function get_cast_for_type($type = '') * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ public function get_sql($type, $primary_table, $primary_id_column, $context = \null) { @@ -41720,6 +42068,7 @@ public function get_sql($type, $primary_table, $primary_id_column, $context = \n * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ protected function get_sql_clauses() { @@ -41741,6 +42090,7 @@ protected function get_sql_clauses() * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ protected function get_sql_for_query(&$query, $depth = 0) { @@ -41764,6 +42114,7 @@ protected function get_sql_for_query(&$query, $depth = 0) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ public function get_sql_for_clause(&$clause, $parent_query, $clause_key = '') { @@ -42022,6 +42373,25 @@ class WP_Network_Query * @type string $search Search term(s) to retrieve matching networks for. Default empty. * @type bool $update_network_cache Whether to prime the cache for found networks. Default true. * } + * @phpstan-param array{ + * network__in?: int[], + * network__not_in?: int[], + * count?: bool, + * fields?: string, + * number?: int, + * offset?: int, + * no_found_rows?: bool, + * orderby?: string|array, + * order?: string, + * domain?: string, + * domain__in?: string[], + * domain__not_in?: string[], + * path?: string, + * path__in?: string[], + * path__not_in?: string[], + * search?: string, + * update_network_cache?: bool, + * } $query */ public function __construct($query = '') { @@ -42772,6 +43142,9 @@ public function __call($name, $arguments) * is not found in the built-in providers list. Default true. * } * @return string|false The oEmbed provider URL on success, false on failure. + * @phpstan-param array{ + * discover?: bool, + * } $args */ public function get_provider($url, $args = '') { @@ -42992,6 +43365,12 @@ public function __construct($extension_type) * @type string $message The error message. * } * @return bool True on success, false on failure. + * @phpstan-param array{ + * type?: string, + * file?: string, + * line?: string, + * message?: string, + * } $error */ public function set($extension, $error) { @@ -44370,6 +44749,80 @@ public function fill_query_vars($array) * @type int $w The week number of the year. Default empty. Accepts numbers 0-53. * @type int $year The four-digit year. Default empty. Accepts any four-digit year. * } + * @phpstan-param array{ + * attachment_id?: int, + * author?: int|string, + * author_name?: string, + * author__in?: int[], + * author__not_in?: int[], + * cache_results?: bool, + * cat?: int|string, + * category__and?: int[], + * category__in?: int[], + * category__not_in?: int[], + * category_name?: string, + * comment_count?: array|int, + * comment_status?: string, + * comments_per_page?: int, + * date_query?: array, + * day?: int, + * exact?: bool, + * fields?: string, + * hour?: int, + * ignore_sticky_posts?: int|bool, + * m?: int, + * meta_compare?: string, + * meta_compare_key?: string, + * meta_key?: string, + * meta_query?: array, + * meta_value?: string, + * meta_value_num?: int, + * meta_type_key?: string, + * menu_order?: int, + * monthnum?: int, + * name?: string, + * nopaging?: bool, + * no_found_rows?: bool, + * offset?: int, + * order?: string, + * orderby?: string|array, + * p?: int, + * page?: int, + * paged?: int, + * page_id?: int, + * pagename?: string, + * perm?: string, + * ping_status?: string, + * post__in?: int[], + * post__not_in?: int[], + * post_mime_type?: string, + * post_name__in?: string[], + * post_parent?: int, + * post_parent__in?: int[], + * post_parent__not_in?: int[], + * post_type?: string|array, + * post_status?: string|array, + * posts_per_page?: int, + * posts_per_archive_page?: int, + * s?: string, + * second?: int, + * sentence?: bool, + * suppress_filters?: bool, + * tag?: string, + * tag__and?: int[], + * tag__in?: int[], + * tag__not_in?: int[], + * tag_id?: int, + * tag_slug__and?: string[], + * tag_slug__in?: string[], + * tax_query?: array, + * title?: string, + * update_post_meta_cache?: bool, + * update_post_term_cache?: bool, + * lazy_load_term_meta?: bool, + * w?: int, + * year?: int, + * } $query */ public function parse_query($query = '') { @@ -45321,6 +45774,10 @@ public function __construct(\WP_Recovery_Mode_Link_Service $link_service) * @type string $type The extension type. Either 'plugin' or 'theme'. * } * @return true|WP_Error True if email sent, WP_Error otherwise. + * @phpstan-param array{ + * slug?: string, + * type?: string, + * } $extension */ public function maybe_send_recovery_mode_email($rate_limit, $error, $extension) { @@ -45769,6 +46226,7 @@ protected function get_link_ttl() * @type string $slug The extension slug. This is the plugin or theme's directory. * @type string $type The extension type. Either 'plugin' or 'theme'. * } + * boop */ protected function get_extension_for_error($error) { @@ -46611,6 +47069,15 @@ public function add_endpoint($name, $places, $query_var = \true) * and rewrite rules built for each in-turn. Default true. * @type bool $endpoints Whether endpoints should be applied to the generated rules. Default true. * } + * @phpstan-param array{ + * with_front?: bool, + * ep_mask?: int, + * paged?: bool, + * feed?: bool, + * forcomments?: bool, + * walk_dirs?: bool, + * endpoints?: bool, + * } $args */ public function add_permastruct($name, $struct, $args = array()) { @@ -47471,6 +47938,45 @@ class WP_Site_Query * comparisons. Default empty. * @type string $meta_compare Comparison operator to test the `$meta_value`. Default empty. * } + * @phpstan-param array{ + * site__in?: int[], + * site__not_in?: int[], + * count?: bool, + * date_query?: array, + * fields?: string, + * ID?: int, + * number?: int, + * offset?: int, + * no_found_rows?: bool, + * orderby?: string|array, + * order?: string, + * network_id?: int, + * network__in?: int[], + * network__not_in?: int[], + * domain?: string, + * domain__in?: string[], + * domain__not_in?: string[], + * path?: string, + * path__in?: string[], + * path__not_in?: string[], + * public?: int, + * archived?: int, + * mature?: int, + * spam?: int, + * deleted?: int, + * lang_id?: int, + * lang__in?: string[], + * lang__not_in?: string[], + * search?: string, + * search_columns?: string[], + * update_site_cache?: bool, + * update_site_meta_cache?: bool, + * meta_query?: array, + * meta_key?: string, + * meta_value?: string, + * meta_type?: string, + * meta_compare?: string, + * } $query */ public function __construct($query = '') { @@ -47957,6 +48463,7 @@ protected static function is_first_order_clause($query) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ public function get_sql($primary_table, $primary_id_column) { @@ -47975,6 +48482,7 @@ public function get_sql($primary_table, $primary_id_column) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ protected function get_sql_clauses() { @@ -47996,6 +48504,7 @@ protected function get_sql_clauses() * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ protected function get_sql_for_query(&$query, $depth = 0) { @@ -48015,6 +48524,7 @@ protected function get_sql_for_query(&$query, $depth = 0) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } + * boop */ public function get_sql_for_clause(&$clause, $parent_query) { @@ -48547,6 +49057,39 @@ class WP_Term_Query * comparisons. Default empty. * @type string $meta_compare Comparison operator to test the 'meta_value'. Default empty. * } + * @phpstan-param array{ + * taxonomy?: string|array, + * object_ids?: int|int[], + * orderby?: string, + * order?: string, + * hide_empty?: bool|int, + * include?: int[]|string, + * exclude?: int[]|string, + * exclude_tree?: int[]|string, + * number?: int|string, + * offset?: int, + * fields?: string, + * count?: bool, + * name?: string|array, + * slug?: string|array, + * term_taxonomy_id?: int|int[], + * hierarchical?: bool, + * search?: string, + * name__like?: string, + * description__like?: string, + * pad_counts?: bool, + * get?: string, + * child_of?: int, + * parent?: int|string, + * childless?: bool, + * cache_domain?: string, + * update_term_meta_cache?: bool, + * meta_query?: array, + * meta_key?: string, + * meta_value?: string, + * meta_type?: string, + * meta_compare?: string, + * } $query */ public function __construct($query = '') { @@ -49052,6 +49595,7 @@ public function _changed($orig, $final) * of `$orig`. A value >= 0 corresponds to index of `$final`. * Value < 0 indicates a blank row. * } + * boop */ public function interleave_changed_lines($orig, $final) { @@ -50816,6 +51360,34 @@ public static function fill_query_vars($args) * @type string[] $login__not_in An array of logins to exclude. Users matching one of these * logins will not be included in results. Default empty array. * } + * @phpstan-param array{ + * blog_id?: int, + * role?: string|array, + * role__in?: string[], + * role__not_in?: string[], + * meta_key?: string, + * meta_value?: string, + * meta_compare?: string, + * include?: int[], + * exclude?: int[], + * search?: string, + * search_columns?: string[], + * orderby?: string|array, + * order?: string, + * offset?: int, + * number?: int, + * paged?: int, + * count_total?: bool, + * fields?: string|array, + * who?: string, + * has_published_posts?: bool|array, + * nicename?: string, + * nicename__in?: string[], + * nicename__not_in?: string[], + * login?: string, + * login__in?: string[], + * login__not_in?: string[], + * } $query */ public function prepare_query($query = array()) { @@ -51909,6 +52481,9 @@ public function is_preview() * * @type int $number Number increment used for multiples of the same widget. * } + * @phpstan-param int|array{ + * number?: int, + * } $widget_args */ public function display_callback($args, $widget_args = 1) { @@ -51937,6 +52512,9 @@ public function update_callback($deprecated = 1) * @type int $number Number increment used for multiples of the same widget. * } * @return string|null + * @phpstan-param int|array{ + * number?: int, + * } $widget_args */ public function form_callback($widget_args = 1) { @@ -52090,6 +52668,10 @@ public function sayHello() * @type int $number2 A second number to add. * } * @return int Sum of the two given numbers. + * @phpstan-param array{ + * number1?: int, + * number2?: int, + * } $args */ public function addTwoNumbers($args) { @@ -52218,6 +52800,10 @@ public function initialise_blog_option_info() * - 'blogid' * - 'blogName' * - 'xmlrpc' - url of xmlrpc endpoint + * @phpstan-param array{ + * username?: string, + * password?: string, + * } $args */ public function wp_getUsersBlogs($args) { @@ -52379,6 +52965,12 @@ protected function _prepare_user($user, $fields) * } * } * @return int|IXR_Error Post ID on success, IXR_Error instance otherwise. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * content_struct?: array, + * } $args */ public function wp_newPost($args) { @@ -52439,6 +53031,13 @@ protected function _insert_post($user, $content_struct) * @type array $content_struct Extra content arguments. * } * @return true|IXR_Error True on success, IXR_Error on failure. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * post_id?: int, + * content_struct?: array, + * } $args */ public function wp_editPost($args) { @@ -52459,6 +53058,12 @@ public function wp_editPost($args) * @type int $post_id Post ID. * } * @return true|IXR_Error True on success, IXR_Error instance on failure. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * post_id?: int, + * } $args */ public function wp_deletePost($args) { @@ -52511,6 +53116,13 @@ public function wp_deletePost($args) * - 'categories' * - 'tags' * - 'enclosure' + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * post_id?: int, + * fields?: array, + * } $args */ public function wp_getPost($args) { @@ -52536,6 +53148,13 @@ public function wp_getPost($args) * @type array $fields Optional. The subset of post type fields to return in the response array. * } * @return array|IXR_Error Array contains a collection of posts. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * filter?: array, + * fields?: array, + * } $args */ public function wp_getPosts($args) { @@ -52558,6 +53177,12 @@ public function wp_getPosts($args) * 'parent', 'description', and 'slug'. * } * @return int|IXR_Error The term ID on success, or an IXR_Error object on failure. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * content_struct?: array, + * } $args */ public function wp_newTerm($args) { @@ -52581,6 +53206,13 @@ public function wp_newTerm($args) * 'description', and 'slug'. * } * @return true|IXR_Error True on success, IXR_Error instance on failure. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * term_id?: int, + * content_struct?: array, + * } $args */ public function wp_editTerm($args) { @@ -52602,6 +53234,13 @@ public function wp_editTerm($args) * @type int $term_id Term ID. * } * @return true|IXR_Error True on success, IXR_Error instance on failure. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * taxnomy_name?: string, + * term_id?: int, + * } $args */ public function wp_deleteTerm($args) { @@ -52632,6 +53271,13 @@ public function wp_deleteTerm($args) * - 'description' * - 'parent' * - 'count' + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * taxnomy?: string, + * term_id?: string, + * } $args */ public function wp_getTerm($args) { @@ -52657,6 +53303,13 @@ public function wp_getTerm($args) * 'offset', 'orderby', 'order', 'hide_empty', and 'search'. Default empty array. * } * @return array|IXR_Error An associative array of terms data on success, IXR_Error instance otherwise. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * taxnomy?: string, + * filter?: array, + * } $args */ public function wp_getTerms($args) { @@ -52680,6 +53333,13 @@ public function wp_getTerms($args) * Default empty array. * } * @return array|IXR_Error An array of taxonomy data on success, IXR_Error instance otherwise. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * taxnomy?: string, + * fields?: array, + * } $args */ public function wp_getTaxonomy($args) { @@ -52702,6 +53362,13 @@ public function wp_getTaxonomy($args) * } * @return array|IXR_Error An associative array of taxonomy data with returned fields determined * by `$fields`, or an IXR_Error instance on failure. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * filter?: array, + * fields?: array, + * } $args */ public function wp_getTaxonomies($args) { @@ -52741,6 +53408,13 @@ public function wp_getTaxonomies($args) * - 'url' * - 'display_name' * - 'roles' + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * user_id?: int, + * fields?: array, + * } $args */ public function wp_getUser($args) { @@ -52768,6 +53442,13 @@ public function wp_getUser($args) * @type array $fields (optional) * } * @return array|IXR_Error users data + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * filter?: array, + * fields?: array, + * } $args */ public function wp_getUsers($args) { @@ -52786,6 +53467,12 @@ public function wp_getUsers($args) * @type array $fields (optional) * } * @return array|IXR_Error (@see wp_getUser) + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * fields?: array, + * } $args */ public function wp_getProfile($args) { @@ -52811,6 +53498,12 @@ public function wp_getProfile($args) * - 'bio' * } * @return true|IXR_Error True, on success. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * content_struct?: array, + * } $args */ public function wp_editProfile($args) { @@ -52829,6 +53522,12 @@ public function wp_editProfile($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * page_id?: int, + * username?: string, + * password?: string, + * } $args */ public function wp_getPage($args) { @@ -52847,6 +53546,12 @@ public function wp_getPage($args) * @type int $num_pages * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * num_pages?: int, + * } $args */ public function wp_getPages($args) { @@ -52867,6 +53572,12 @@ public function wp_getPages($args) * @type array $content_struct * } * @return int|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * content_struct?: array, + * } $args */ public function wp_newPage($args) { @@ -52885,6 +53596,12 @@ public function wp_newPage($args) * @type int $page_id * } * @return true|IXR_Error True, if success. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * page_id?: int, + * } $args */ public function wp_deletePage($args) { @@ -52905,6 +53622,14 @@ public function wp_deletePage($args) * @type string $publish * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * page_id?: int, + * username?: string, + * password?: string, + * content?: string, + * publish?: string, + * } $args */ public function wp_editPage($args) { @@ -52924,6 +53649,11 @@ public function wp_editPage($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function wp_getPageList($args) { @@ -52941,6 +53671,11 @@ public function wp_getPageList($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function wp_getAuthors($args) { @@ -52958,6 +53693,11 @@ public function wp_getAuthors($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function wp_getTags($args) { @@ -52976,6 +53716,12 @@ public function wp_getTags($args) * @type array $category * } * @return int|IXR_Error Category ID. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * category?: array, + * } $args */ public function wp_newCategory($args) { @@ -52994,6 +53740,12 @@ public function wp_newCategory($args) * @type int $category_id * } * @return bool|IXR_Error See wp_delete_term() for return info. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * category_id?: int, + * } $args */ public function wp_deleteCategory($args) { @@ -53013,6 +53765,13 @@ public function wp_deleteCategory($args) * @type int $max_results * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * category?: array, + * max_results?: int, + * } $args */ public function wp_suggestCategories($args) { @@ -53031,6 +53790,12 @@ public function wp_suggestCategories($args) * @type int $comment_id * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * comment_id?: int, + * } $args */ public function wp_getComment($args) { @@ -53060,6 +53825,12 @@ public function wp_getComment($args) * @type array $struct * } * @return array|IXR_Error Contains a collection of comments. See wp_xmlrpc_server::wp_getComment() for a description of each item contents + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * struct?: array, + * } $args */ public function wp_getComments($args) { @@ -53081,6 +53852,12 @@ public function wp_getComments($args) * @type int $comment_ID * } * @return bool|IXR_Error See wp_delete_comment(). + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * comment_ID?: int, + * } $args */ public function wp_deleteComment($args) { @@ -53111,6 +53888,13 @@ public function wp_deleteComment($args) * @type array $content_struct * } * @return true|IXR_Error True, on success. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * comment_ID?: int, + * content_struct?: array, + * } $args */ public function wp_editComment($args) { @@ -53130,6 +53914,13 @@ public function wp_editComment($args) * @type array $content_struct * } * @return int|IXR_Error See wp_new_comment(). + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * post?: string|int, + * content_struct?: array, + * } $args */ public function wp_newComment($args) { @@ -53147,6 +53938,11 @@ public function wp_newComment($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function wp_getCommentStatusList($args) { @@ -53165,6 +53961,12 @@ public function wp_getCommentStatusList($args) * @type int $post_id * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * post_id?: int, + * } $args */ public function wp_getCommentCount($args) { @@ -53182,6 +53984,11 @@ public function wp_getCommentCount($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function wp_getPostStatusList($args) { @@ -53199,6 +54006,11 @@ public function wp_getPostStatusList($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function wp_getPageStatusList($args) { @@ -53216,6 +54028,11 @@ public function wp_getPageStatusList($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function wp_getPageTemplates($args) { @@ -53234,6 +54051,12 @@ public function wp_getPageTemplates($args) * @type array $options * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * options?: array, + * } $args */ public function wp_getOptions($args) { @@ -53263,6 +54086,12 @@ public function _getOptions($options) * @type array $options * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * options?: array, + * } $args */ public function wp_setOptions($args) { @@ -53289,6 +54118,12 @@ public function wp_setOptions($args) * - 'caption' * - 'description' * - 'metadata' + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * attachment_id?: int, + * } $args */ public function wp_getMediaItem($args) { @@ -53318,6 +54153,12 @@ public function wp_getMediaItem($args) * @type array $struct * } * @return array|IXR_Error Contains a collection of media items. See wp_xmlrpc_server::wp_getMediaItem() for a description of each item contents + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * struct?: array, + * } $args */ public function wp_getMediaLibrary($args) { @@ -53335,6 +54176,11 @@ public function wp_getMediaLibrary($args) * @type string $password * } * @return array|IXR_Error List of post formats, otherwise IXR_Error object. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function wp_getPostFormats($args) { @@ -53365,6 +54211,13 @@ public function wp_getPostFormats($args) * - 'menu_position' * - 'taxonomies' * - 'supports' + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * post_type_name?: string, + * fields?: array, + * } $args */ public function wp_getPostType($args) { @@ -53386,6 +54239,13 @@ public function wp_getPostType($args) * @type array $fields (optional) * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * filter?: array, + * fields?: array, + * } $args */ public function wp_getPostTypes($args) { @@ -53411,6 +54271,13 @@ public function wp_getPostTypes($args) * @type array $fields (optional) * } * @return array|IXR_Error contains a collection of posts. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * post_id?: int, + * fields?: array, + * } $args */ public function wp_getRevisions($args) { @@ -53431,6 +54298,12 @@ public function wp_getRevisions($args) * @type int $revision_id * } * @return bool|IXR_Error false if there was an error restoring, true if success. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * revision_id?: int, + * } $args */ public function wp_restoreRevision($args) { @@ -53454,6 +54327,11 @@ public function wp_restoreRevision($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function blogger_getUsersBlogs($args) { @@ -53470,6 +54348,10 @@ public function blogger_getUsersBlogs($args) * @type string $password Password. * } * @return array|IXR_Error + * @phpstan-param array{ + * username?: string, + * password?: string, + * } $args */ protected function _multisite_getUsersBlogs($args) { @@ -53489,6 +54371,11 @@ protected function _multisite_getUsersBlogs($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function blogger_getUserInfo($args) { @@ -53507,6 +54394,12 @@ public function blogger_getUserInfo($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * post_ID?: int, + * username?: string, + * password?: string, + * } $args */ public function blogger_getPost($args) { @@ -53526,6 +54419,13 @@ public function blogger_getPost($args) * @type int $numberposts (optional) * } * @return array|IXR_Error + * @phpstan-param array{ + * appkey?: string, + * blog_id?: int, + * username?: string, + * password?: string, + * numberposts?: int, + * } $args */ public function blogger_getRecentPosts($args) { @@ -53570,6 +54470,14 @@ public function blogger_setTemplate($args) * @type string $publish * } * @return int|IXR_Error + * @phpstan-param array{ + * appkey?: string, + * blog_id?: int, + * username?: string, + * password?: string, + * content?: string, + * publish?: string, + * } $args */ public function blogger_newPost($args) { @@ -53590,6 +54498,14 @@ public function blogger_newPost($args) * @type bool $publish * } * @return true|IXR_Error true when done. + * @phpstan-param array{ + * blog_id?: int, + * post_ID?: int, + * username?: string, + * password?: string, + * content?: string, + * publish?: bool, + * } $args */ public function blogger_editPost($args) { @@ -53608,6 +54524,12 @@ public function blogger_editPost($args) * @type string $password * } * @return true|IXR_Error True when post is deleted. + * @phpstan-param array{ + * blog_id?: int, + * post_ID?: int, + * username?: string, + * password?: string, + * } $args */ public function blogger_deletePost($args) { @@ -53653,6 +54575,13 @@ public function blogger_deletePost($args) * @type int $publish * } * @return int|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * content_struct?: array, + * publish?: int, + * } $args */ public function mw_newPost($args) { @@ -53696,6 +54625,13 @@ public function attach_uploads($post_ID, $post_content) * @type int $publish * } * @return true|IXR_Error True on success. + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * content_struct?: array, + * publish?: int, + * } $args */ public function mw_editPost($args) { @@ -53714,6 +54650,12 @@ public function mw_editPost($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * post_ID?: int, + * username?: string, + * password?: string, + * } $args */ public function mw_getPost($args) { @@ -53732,6 +54674,12 @@ public function mw_getPost($args) * @type int $numberposts * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * numberposts?: int, + * } $args */ public function mw_getRecentPosts($args) { @@ -53749,6 +54697,11 @@ public function mw_getRecentPosts($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function mw_getCategories($args) { @@ -53773,6 +54726,12 @@ public function mw_getCategories($args) * @type array $data * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * data?: array, + * } $args */ public function mw_newMediaObject($args) { @@ -53795,6 +54754,12 @@ public function mw_newMediaObject($args) * @type int $numberposts * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * numberposts?: int, + * } $args */ public function mt_getRecentPostTitles($args) { @@ -53812,6 +54777,11 @@ public function mt_getRecentPostTitles($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * blog_id?: int, + * username?: string, + * password?: string, + * } $args */ public function mt_getCategoryList($args) { @@ -53829,6 +54799,11 @@ public function mt_getCategoryList($args) * @type string $password * } * @return array|IXR_Error + * @phpstan-param array{ + * post_ID?: int, + * username?: string, + * password?: string, + * } $args */ public function mt_getPostCategories($args) { @@ -53847,6 +54822,12 @@ public function mt_getPostCategories($args) * @type array $categories * } * @return true|IXR_Error True on success. + * @phpstan-param array{ + * post_ID?: int, + * username?: string, + * password?: string, + * categories?: array, + * } $args */ public function mt_setPostCategories($args) { @@ -53895,6 +54876,11 @@ public function mt_getTrackbackPings($post_ID) * @type string $password * } * @return int|IXR_Error + * @phpstan-param array{ + * post_ID?: int, + * username?: string, + * password?: string, + * } $args */ public function mt_publishPost($args) { @@ -53915,6 +54901,10 @@ public function mt_publishPost($args) * @type string $pagelinkedto * } * @return string|IXR_Error + * @phpstan-param array{ + * pagelinkedfrom?: string, + * pagelinkedto?: string, + * } $args */ public function pingback_ping($args) { @@ -56848,6 +57838,12 @@ public function sanitize($value) * @type bool $auto_add Whether pages will auto_add to this menu. Default false. * } * @return null|void + * @phpstan-param false|array{ + * name?: string, + * description?: string, + * parent?: int, + * auto_add?: bool, + * } $value */ protected function update($value) { @@ -57171,6 +58167,16 @@ class WP_Customize_Partial * A partial render is considered a failure if the render_callback returns * false. * } + * @phpstan-param array{ + * type?: string, + * selector?: string, + * settings?: string[], + * primary_setting?: string, + * capability?: string, + * render_callback?: callable, + * container_inclusive?: bool, + * fallback_refresh?: bool, + * } $args */ public function __construct(\WP_Customize_Selective_Refresh $component, $id, $args = array()) { @@ -57186,6 +58192,7 @@ public function __construct(\WP_Customize_Selective_Refresh $component, $id, $ar * @type string $base ID base. * @type array $keys Keys for multidimensional array. * } + * boop */ public final function id_data() { @@ -59749,6 +60756,7 @@ public function serve_request($path = \null) * @type array $_links Links. * @type array $_embedded Embedded objects. * } + * boop */ public function response_to_data($response, $embed) { @@ -59795,6 +60803,7 @@ public static function get_compact_response_links($response) * @type array $_links Links. * @type array $_embedded Embedded objects. * } + * boop */ protected function embed_links($data, $embed = \true) { @@ -59939,6 +60948,9 @@ protected function get_json_last_error() * @type string $context Context. * } * @return WP_REST_Response The API root index data. + * @phpstan-param array{ + * context?: string, + * } $request */ public function get_index($request) { @@ -68313,6 +69325,11 @@ public function _register_one($number = -1) * @type bool $legacy Whether widget is in legacy mode. * } * @return bool Whether Text widget instance contains legacy data. + * @phpstan-param array{ + * text?: string, + * filter?: bool|string, + * legacy?: bool, + * } $instance */ public function is_legacy_instance($instance) { @@ -68969,6 +69986,7 @@ public function init_charset() * @type string $charset Character set. * @type string $collate Collation. * } + * boop */ public function determine_charset($charset, $collate) { @@ -70986,6 +72004,22 @@ function get_link_to_edit($link) * } * @param bool $wp_error Optional. Whether to return a WP_Error object on failure. Default false. * @return int|WP_Error Value 0 or WP_Error on failure. The link ID on success. + * @phpstan-param array{ + * link_id?: int, + * link_url?: string, + * link_name?: string, + * link_image?: string, + * link_target?: string, + * link_description?: string, + * link_visible?: string, + * link_owner?: int, + * link_rating?: int, + * link_updated?: string, + * link_rel?: string, + * link_notes?: string, + * link_rss?: string, + * link_category?: int, + * } $linkdata */ function wp_insert_link($linkdata, $wp_error = \false) { @@ -71416,6 +72450,13 @@ function wp_dashboard_site_activity() * @type string $id The container id. * } * @return bool False if no posts were found. True otherwise. + * @phpstan-param array{ + * max?: int, + * status?: string, + * order?: string, + * title?: string, + * id?: string, + * } $args */ function wp_dashboard_recent_posts($args) { @@ -72487,6 +73528,14 @@ function _wp_privacy_requests_screen_options() * 'publish', 'pending', 'draft', 'auto-draft', 'future', 'private', 'inherit', or * 'trash'. Default false (all statuses except 'auto-draft'). * } + * @phpstan-param array{ + * content?: string, + * author?: string, + * category?: string, + * start_date?: string, + * end_date?: string, + * status?: string, + * } $args */ function export_wp($args = array()) { @@ -72582,6 +73631,13 @@ function wp_print_file_editor_templates() * @type string $nonce Nonce. * } * @return true|WP_Error True on success or `WP_Error` on failure. + * @phpstan-param array{ + * file?: string, + * plugin?: string, + * theme?: string, + * newcontent?: string, + * nonce?: string, + * } $args */ function wp_edit_theme_plugin_file($args) { @@ -72651,6 +73707,15 @@ function validate_file_to_edit($file, $allowed_files = array()) * @return string[] On success, returns an associative array of file attributes. * On failure, returns `$overrides['upload_error_handler']( &$file, $message )` * or `array( 'error' => $message )`. + * @phpstan-param false|array{ + * upload_error_handler?: callable, + * unique_filename_callback?: callable, + * upload_error_strings?: string[], + * test_form?: bool, + * test_size?: bool, + * test_type?: bool, + * mimes?: string[], + * } $overrides */ function _wp_handle_upload(&$file, $overrides, $time, $action) { @@ -74104,6 +75169,12 @@ function sort_menu($a, $b) * @type callable $callback Meta box display callback. * @type array $args Extra meta box arguments. * } + * @phpstan-param array{ + * id?: string, + * title?: string, + * callback?: callable, + * args?: array, + * } $args */ function post_submit_meta_box($post, $args = array()) { @@ -74132,6 +75203,12 @@ function attachment_submit_meta_box($post) * @type callable $callback Meta box display callback. * @type array $args Extra meta box arguments. * } + * @phpstan-param array{ + * id?: string, + * title?: string, + * callback?: callable, + * args?: array, + * } $box */ function post_format_meta_box($post, $box) { @@ -74156,6 +75233,12 @@ function post_format_meta_box($post, $box) * @type string $taxonomy Taxonomy. Default 'post_tag'. * } * } + * @phpstan-param array{ + * id?: string, + * title?: string, + * callback?: callable, + * args?: array, + * } $box */ function post_tags_meta_box($post, $box) { @@ -74180,6 +75263,12 @@ function post_tags_meta_box($post, $box) * @type string $taxonomy Taxonomy. Default 'category'. * } * } + * @phpstan-param array{ + * id?: string, + * title?: string, + * callback?: callable, + * args?: array, + * } $box */ function post_categories_meta_box($post, $box) { @@ -75159,6 +76248,11 @@ function network_settings_add_js() * @type array $links The tabs to include with (label|url|cap) keys. * @type string $selected The ID of the selected link. * } + * @phpstan-param array{ + * blog_id?: int, + * links?: array, + * selected?: string, + * } $args */ function network_edit_site_nav($args = array()) { @@ -75270,6 +76364,12 @@ function wp_nav_menu_item_link_meta_box() * @type callable $callback Meta box display callback. * @type WP_Post_Type $args Extra meta box arguments (the post type object for this meta box). * } + * @phpstan-param array{ + * id?: string, + * title?: string, + * callback?: callable, + * args?: WP_Post_Type, + * } $box */ function wp_nav_menu_item_post_type_meta_box($object, $box) { @@ -75290,6 +76390,12 @@ function wp_nav_menu_item_post_type_meta_box($object, $box) * @type callable $callback Meta box display callback. * @type object $args Extra meta box arguments (the taxonomy object for this meta box). * } + * @phpstan-param array{ + * id?: string, + * title?: string, + * callback?: callable, + * args?: object, + * } $box */ function wp_nav_menu_item_taxonomy_meta_box($object, $box) { @@ -75589,6 +76695,21 @@ function options_reading_blog_charset() * @return object|array|WP_Error Response object or array on success, WP_Error on failure. See the * {@link https://developer.wordpress.org/reference/functions/plugins_api/ function reference article} * for more information on the make-up of possible return values depending on the value of `$action`. + * @phpstan-param object|array{ + * slug?: string, + * per_page?: int, + * page?: int, + * number?: int, + * search?: string, + * tag?: string, + * author?: string, + * user?: string, + * browse?: string, + * locale?: string, + * installed_plugins?: string, + * is_ssl?: bool, + * fields?: array, + * } $args */ function plugins_api($action, $args = array()) { @@ -75662,6 +76783,7 @@ function display_plugins_table() * @type string $version The most recent version of the plugin. * @type string $file Plugin filename relative to the plugins directory. * } + * boop */ function install_plugin_install_status($api, $loop = \false) { @@ -75742,6 +76864,7 @@ function install_plugin_information() * @type string $RequiresPHP Minimum required version of PHP. * @type string $UpdateURI ID of the plugin for update purposes, should be a URI. * } + * boop */ function get_plugin_data($plugin_file, $markup = \true, $translate = \true) { @@ -75773,6 +76896,7 @@ function get_plugin_data($plugin_file, $markup = \true, $translate = \true) * @type string $DomainPath Plugins relative directory path to .mo files. * @type bool $Network Whether the plugin can only be activated network-wide. * } + * boop */ function _get_plugin_data_markup_translate($plugin_file, $plugin_data, $markup = \true, $translate = \true) { @@ -76998,6 +78122,7 @@ function postbox_classes($box_id, $screen_id) * @type string $0 The permalink with placeholder for the post name. * @type string $1 The post name. * } + * boop */ function get_sample_permalink($id, $title = \null, $name = \null) { @@ -77256,6 +78381,10 @@ function _wp_personal_data_cleanup_requests() * @param string $group_id The group identifier. * @param int $groups_count The number of all groups * @return string The HTML for this group and its items. + * @phpstan-param array{ + * group_label?: string, + * items?: array, + * } $group_data */ function wp_privacy_generate_personal_data_export_group_html($group_data, $group_id = '', $groups_count = 1) { @@ -77691,6 +78820,14 @@ function wp_create_categories($categories, $post_id = '') * @param bool $wp_error Optional. Default false. * @return int|object The ID number of the new or updated Category on success. Zero or a WP_Error on failure, * depending on param $wp_error. + * @phpstan-param array{ + * cat_ID?: int, + * taxonomy?: string, + * cat_name?: string, + * category_description?: string, + * category_nicename?: string, + * category_parent?: int|string, + * } $catarr */ function wp_insert_category($catarr, $wp_error = \false) { @@ -77821,6 +78958,15 @@ function wp_category_checklist($post_id = 0, $descendants_and_self = 0, $selecte * of echoing it. Default true. * } * @return string HTML list of input elements. + * @phpstan-param array{ + * descendants_and_self?: int, + * selected_cats?: int[], + * popular_cats?: int[], + * walker?: Walker, + * taxonomy?: string, + * checked_ontop?: bool, + * echo?: bool, + * } $args */ function wp_terms_checklist($post_id = 0, $args = array()) { @@ -78036,6 +79182,12 @@ function add_meta_box($id, $title, $callback, $screen = \null, $context = 'advan * @type callable $old_callback The original callback for this meta box. * @type array $args Extra meta box arguments. * } + * @phpstan-param array{ + * id?: string, + * title?: string, + * old_callback?: callable, + * args?: array, + * } $box */ function do_block_editor_incompatible_meta_box($object, $box) { @@ -78172,6 +79324,10 @@ function add_settings_section($id, $title, $callback, $page) * @type string $class CSS Class to be added to the `` element when the * field is output. * } + * @phpstan-param array{ + * label_for?: string, + * class?: string, + * } $args */ function add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array()) { @@ -78268,6 +79424,7 @@ function add_settings_error($setting, $code, $message, $type = 'error') * @type string $type Optional. Message type, controls HTML class. Possible values include 'error', * 'success', 'warning', 'info'. Default 'error'. * } + * boop */ function get_settings_errors($setting = '', $sanitize = \false) { @@ -78532,6 +79689,12 @@ function _local_storage_notice() * of echoing it. Default true. * } * @return string Star rating HTML. + * @phpstan-param array{ + * rating?: int|float, + * type?: string, + * number?: int, + * echo?: bool, + * } $args */ function wp_star_rating($args = array()) { @@ -78812,6 +79975,19 @@ function get_theme_feature_list($api = \true) * @return object|array|WP_Error Response object or array on success, WP_Error on failure. See the * {@link https://developer.wordpress.org/reference/functions/themes_api/ function reference article} * for more information on the make-up of possible return objects depending on the value of `$action`. + * @phpstan-param object|array{ + * slug?: string, + * per_page?: int, + * page?: int, + * number?: int, + * search?: string, + * tag?: string, + * author?: string, + * user?: string, + * browse?: string, + * locale?: string, + * fields?: array, + * } $args */ function themes_api($action, $args = array()) { @@ -79391,6 +80567,7 @@ function wp_get_auto_update_message() * @type string $password The password of the site owner, if their user account didn't already exist. * @type string $password_message The explanatory message regarding the password. * } + * boop */ function wp_install($blog_title, $user_name, $user_email, $public, $deprecated = '', $user_password = '', $language = '') { @@ -80339,6 +81516,12 @@ function admin_created_user_email($text) * } * @param WP_User $user The user authorizing the application. * @return true|WP_Error True if the request is valid, a WP_Error object contains errors if not. + * @phpstan-param array{ + * app_name?: string, + * app_id?: string, + * success_url?: string, + * reject_url?: string, + * } $request */ function wp_is_authorize_application_password_request_valid($request, $user) { @@ -81174,6 +82357,23 @@ function get_author_posts_url($author_id, $author_nicename = '') * @type int[]|string $include Array or comma/space-separated list of author IDs to include. Default empty. * } * @return void|string Void if 'echo' argument is true, list of authors if 'echo' is false. + * @phpstan-param array{ + * orderby?: string, + * order?: string, + * number?: int, + * optioncount?: bool, + * exclude_admin?: bool, + * show_fullname?: bool, + * hide_empty?: bool, + * feed?: string, + * feed_image?: string, + * feed_type?: string, + * echo?: bool, + * style?: string, + * html?: bool, + * exclude?: int[]|string, + * include?: int[]|string, + * } $args */ function wp_list_authors($args = '') { @@ -81871,6 +83071,10 @@ function _build_template_result_from_post($post) * } * @param string $template_type Optional. The template type (post type). Default 'wp_template'. * @return WP_Block_Template[] Block template objects. + * @phpstan-param array{ + * slug__in?: array, + * wp_id?: int, + * } $query */ function get_block_templates($query = array(), $template_type = 'wp_template') { @@ -83355,6 +84559,18 @@ function register_block_core_tag_cloud() * * } * @return string Formatted output in HTML + * @phpstan-param array{ + * show_updated?: int|bool, + * show_description?: int|bool, + * show_images?: int|bool, + * show_name?: int|bool, + * before?: string, + * after?: string, + * link_before?: string, + * link_after?: string, + * between?: string, + * show_rating?: int|bool, + * } $args */ function _walk_bookmarks($bookmarks, $args = '') { @@ -83411,6 +84627,26 @@ function _walk_bookmarks($bookmarks, $args = '') * Default 'ASC'. * } * @return void|string Void if 'echo' argument is true, HTML list of bookmarks if 'echo' is false. + * @phpstan-param array{ + * orderby?: string, + * order?: string, + * limit?: int, + * category?: string, + * category_name?: string, + * hide_invisible?: int|bool, + * show_updated?: int|bool, + * echo?: int|bool, + * categorize?: int|bool, + * show_description?: int|bool, + * title_li?: string, + * title_before?: string, + * title_after?: string, + * class?: string|array, + * category_before?: string, + * category_after?: string, + * category_orderby?: string, + * category_order?: string, + * } $args */ function wp_list_bookmarks($args = '') { @@ -83489,6 +84725,18 @@ function get_bookmark_field($field, $bookmark, $context = 'display') * Default empty. * } * @return object[] List of bookmark row objects. + * @phpstan-param array{ + * orderby?: string, + * order?: string, + * limit?: int, + * category?: string, + * category_name?: string, + * hide_invisible?: int|bool, + * show_updated?: int|bool, + * include?: string, + * exclude?: string, + * search?: string, + * } $args */ function get_bookmarks($args = '') { @@ -84356,6 +85604,26 @@ function category_description($category = 0) * Default false. * } * @return string HTML dropdown list of categories. + * @phpstan-param array{ + * show_option_all?: string, + * show_option_none?: string, + * option_none_value?: string, + * orderby?: string, + * pad_counts?: bool, + * show_count?: bool|int, + * echo?: bool|int, + * hierarchical?: bool|int, + * depth?: int, + * tab_index?: int, + * name?: string, + * id?: string, + * class?: string, + * selected?: int|string, + * value_field?: string, + * taxonomy?: string|array, + * hide_if_empty?: bool, + * required?: bool, + * } $args */ function wp_dropdown_categories($args = '') { @@ -84406,6 +85674,25 @@ function wp_dropdown_categories($args = '') * } * @return void|string|false Void if 'echo' argument is true, HTML list of categories if 'echo' is false. * False if the taxonomy does not exist. + * @phpstan-param array{ + * current_category?: int|int[], + * depth?: int, + * echo?: bool|int, + * exclude?: int[]|string, + * exclude_tree?: int[]|string, + * feed?: string, + * feed_image?: string, + * feed_type?: string, + * hide_title_if_empty?: bool, + * separator?: string, + * show_count?: bool|int, + * show_option_all?: string, + * show_option_none?: string, + * style?: string, + * taxonomy?: string, + * title_li?: string, + * use_desc_for_title?: bool|int, + * } $args */ function wp_list_categories($args = '') { @@ -84435,6 +85722,12 @@ function wp_list_categories($args = '') * } * @return void|string|string[] Void if 'echo' argument is true, or on failure. Otherwise, tag cloud * as a string or an array, depending on 'format' argument. + * @phpstan-param array{ + * number?: int, + * link?: string, + * post_type?: string, + * echo?: bool, + * } $args */ function wp_tag_cloud($args = '') { @@ -84495,6 +85788,21 @@ function default_topic_count_scale($count) * 0, 1, or their bool equivalents. * } * @return string|string[] Tag cloud as a string or an array, depending on 'format' argument. + * @phpstan-param array{ + * smallest?: int, + * largest?: int, + * unit?: string, + * number?: int, + * format?: string, + * separator?: string, + * orderby?: string, + * order?: string, + * filter?: int|bool, + * topic_count_text?: string, + * topic_count_text_callback?: callable, + * topic_count_scale_callback?: callable, + * show_count?: bool|int, + * } $args */ function wp_generate_tag_cloud($tags, $args = '') { @@ -84692,6 +86000,12 @@ function get_the_term_list($post_id, $taxonomy, $before = '', $sep = '', $after * @type bool $inclusive Include the term to get the parents for. Default true. * } * @return string|WP_Error A list of term parents on success, WP_Error or empty string on failure. + * @phpstan-param array{ + * format?: string, + * separator?: string, + * link?: bool, + * inclusive?: bool, + * } $args */ function get_term_parents_list($term_id, $taxonomy, $args = array()) { @@ -84798,6 +86112,9 @@ function has_term($term = '', $taxonomy = '', $post = \null) * @type string $taxonomy Taxonomy to retrieve terms for. Default 'category'. * } * @return array List of category objects. + * @phpstan-param array{ + * taxonomy?: string, + * } $args */ function get_categories($args = '') { @@ -84938,6 +86255,9 @@ function sanitize_category_field($field, $value, $cat_id, $context) * } * @return WP_Term[]|int|WP_Error Array of 'post_tag' term objects, a count thereof, * or WP_Error if any of the taxonomies do not exist. + * @phpstan-param array{ + * taxonomy?: string, + * } $args */ function get_tags($args = '') { @@ -85432,6 +86752,13 @@ function comment_ID() * and `$per_page`. * } * @return string The permalink to the given comment. + * @phpstan-param array{ + * type?: string, + * page?: int, + * per_page?: int, + * max_depth?: int, + * cpage?: int|string, + * } $args */ function get_comment_link($comment = \null, $args = array()) { @@ -85743,6 +87070,16 @@ function comments_popup_link($zero = \false, $one = \false, $more = \false, $css * @param int|WP_Post $post Post ID or WP_Post object the comment is going to be displayed on. * Default current post. * @return string|false|null Link to show comment form, if successful. False, if comments are closed. + * @phpstan-param array{ + * add_below?: string, + * respond_id?: string, + * reply_text?: string, + * login_text?: string, + * max_depth?: int, + * depth?: int, + * before?: string, + * after?: string, + * } $args */ function get_comment_reply_link($args = array(), $comment = \null, $post = \null) { @@ -85784,6 +87121,14 @@ function comment_reply_link($args = array(), $comment = \null, $post = \null) * @param int|WP_Post $post Optional. Post ID or WP_Post object the comment is going to be displayed on. * Default current post. * @return string|false|null Link to show comment form, if successful. False, if comments are closed. + * @phpstan-param array{ + * add_below?: string, + * respond_id?: string, + * reply_text?: string, + * login_text?: string, + * before?: string, + * after?: string, + * } $args */ function get_post_reply_link($args = array(), $post = \null) { @@ -85917,6 +87262,22 @@ function comment_form_title($no_reply_text = \false, $reply_text = \false, $link * @param WP_Comment[] $comments Optional. Array of WP_Comment objects. * @return void|string Void if 'echo' argument is true, or no comments to list. * Otherwise, HTML list of comments. + * @phpstan-param array{ + * walker?: object, + * max_depth?: int, + * style?: string, + * callback?: callable, + * end-callback?: callable, + * type?: string, + * page?: int, + * per_page?: int, + * avatar_size?: int, + * reverse_top_level?: bool, + * reverse_children?: bool, + * format?: string, + * short_ping?: bool, + * echo?: bool, + * } $args */ function wp_list_comments($args = array(), $comments = \null) { @@ -85986,6 +87347,32 @@ function wp_list_comments($args = array(), $comments = \null) * @type string $format The comment form format. Default 'xhtml'. Accepts 'xhtml', 'html5'. * } * @param int|WP_Post $post_id Post ID or WP_Post object to generate the form for. Default current post. + * @phpstan-param array{ + * fields?: array, + * comment_field?: string, + * must_log_in?: string, + * logged_in_as?: string, + * comment_notes_before?: string, + * comment_notes_after?: string, + * action?: string, + * id_form?: string, + * id_submit?: string, + * class_container?: string, + * class_form?: string, + * class_submit?: string, + * name_submit?: string, + * title_reply?: string, + * title_reply_to?: string, + * title_reply_before?: string, + * title_reply_after?: string, + * cancel_reply_before?: string, + * cancel_reply_after?: string, + * cancel_reply_link?: string, + * label_submit?: string, + * submit_button?: string, + * submit_field?: string, + * format?: string, + * } $args */ function comment_form($args = array(), $post_id = \null) { @@ -86368,6 +87755,11 @@ function get_comment_pages_count($comments = \null, $per_page = \null, $threaded * Defaults to the value of the 'thread_comments_depth' option. * } * * @return int|null Comment page number or null on error. + * @phpstan-param array{ + * type?: string, + * per_page?: int, + * max_depth?: int|string, + * } $args */ function get_page_of_comment($comment_ID, $args = array()) { @@ -86435,6 +87827,7 @@ function wp_check_comment_disallowed_list($author, $email, $url, $comment, $user * @type int $total_comments The total number of non-trashed comments, including spam. * @type int $all The total number of pending or approved comments. * } + * boop */ function wp_count_comments($post_id = 0) { @@ -86569,6 +87962,7 @@ function _clear_modified_cache_on_transition_comment_status($new_status, $old_st * @type string $comment_author_email The email address of the current commenter, or an empty string. * @type string $comment_author_url The URL address of the current commenter, or an empty string. * } + * boop */ function wp_get_current_commenter() { @@ -86622,6 +88016,23 @@ function wp_get_unapproved_comment_author_email() * @type int $user_id ID of the user who submitted the comment. Default 0. * } * @return int|false The new comment's ID on success, false on failure. + * @phpstan-param array{ + * comment_agent?: string, + * comment_approved?: int|string, + * comment_author?: string, + * comment_author_email?: string, + * comment_author_IP?: string, + * comment_author_url?: string, + * comment_content?: string, + * comment_date?: string, + * comment_date_gmt?: string, + * comment_karma?: int, + * comment_parent?: int, + * comment_post_ID?: int, + * comment_type?: string, + * comment_meta?: array, + * user_id?: int, + * } $commentdata */ function wp_insert_comment($commentdata) { @@ -86700,6 +88111,21 @@ function wp_throttle_comment_flood($block, $time_lastcomment, $time_newcomment) * @param bool $wp_error Should errors be returned as WP_Error objects instead of * executing wp_die()? Default false. * @return int|false|WP_Error The ID of the comment on success, false or WP_Error on failure. + * @phpstan-param array{ + * comment_author?: string, + * comment_author_email?: string, + * comment_author_url?: string, + * comment_content?: string, + * comment_date?: string, + * comment_date_gmt?: string, + * comment_type?: string, + * comment_parent?: int, + * comment_post_ID?: int, + * user_id?: int, + * user_ID?: int, + * comment_agent?: string, + * comment_author_IP?: string, + * } $commentdata */ function wp_new_comment($commentdata, $wp_error = \false) { @@ -87071,6 +88497,15 @@ function _close_comments_for_old_post($open, $post_id) * @type string $_wp_unfiltered_html_comment The nonce value for allowing unfiltered HTML. * } * @return WP_Comment|WP_Error A WP_Comment object on success, a WP_Error object on failure. + * @phpstan-param array{ + * comment_post_ID?: string|int, + * author?: string, + * email?: string, + * url?: string, + * comment?: string, + * comment_parent?: string|int, + * _wp_unfiltered_html_comment?: string, + * } $comment_data */ function wp_handle_comment_submission($comment_data) { @@ -90414,6 +91849,7 @@ function wp_embed_unregister_handler($id, $priority = 10) * @type int $0 The embed width. * @type int $1 The embed height. * } + * boop */ function wp_embed_defaults($url = '') { @@ -90436,6 +91872,11 @@ function wp_embed_defaults($url = '') * is not found in the built-in providers list. Default true. * } * @return string|false The embed HTML on success, false on failure. + * @phpstan-param array{ + * width?: int|string, + * height?: int|string, + * discover?: bool, + * } $args */ function wp_oembed_get($url, $args = '') { @@ -94327,6 +95768,7 @@ function wp_get_upload_dir() * @type string $baseurl URL path without subdir. * @type string|false $error False or error message. * } + * boop */ function wp_upload_dir($time = \null, $create_dir = \true, $refresh_cache = \false) { @@ -94420,6 +95862,7 @@ function _wp_check_existing_file_names($filename, $files) * @type string $type File type. * @type string|false $error Error message, if there has been an error. * } + * boop */ function wp_upload_bits($name, $deprecated, $bits, $time = \null) { @@ -94463,6 +95906,7 @@ function wp_get_default_extension_for_mime_type($mime_type) * @type string|false $ext File extension, or false if the file doesn't match a mime type. * @type string|false $type File mime type, or false if the file doesn't match a mime type. * } + * boop */ function wp_check_filetype($filename, $mimes = \null) { @@ -94490,6 +95934,7 @@ function wp_check_filetype($filename, $mimes = \null) * @type string|false $type File mime type, or false if the file doesn't match a mime type. * @type string|false $proper_filename File name with its correct extension, or false if it cannot be determined. * } + * boop */ function wp_check_filetype_and_ext($file, $filename, $mimes = \null) { @@ -94603,6 +96048,16 @@ function wp_nonce_ays($action) * is a WP_Error. * @type bool $exit Whether to exit the process after completion. Default true. * } + * @phpstan-param int|array{ + * response?: int, + * link_url?: string, + * link_text?: string, + * back_link?: bool, + * text_direction?: string, + * charset?: string, + * code?: string, + * exit?: bool, + * } $args */ function wp_die($message = '', $title = '', $args = array()) { @@ -94732,6 +96187,7 @@ function _scalar_wp_die_handler($message = '', $title = '', $args = array()) * @type string $1 Error title. * @type array $2 Arguments to control behavior. * } + * boop */ function _wp_die_process_input($message, $title = '', $args = array()) { @@ -97011,6 +98467,10 @@ function get_template_part($slug, $name = \null, $args = array()) * accessibility. Default empty. * } * @return void|string Void if 'echo' argument is true, search form HTML if 'echo' is false. + * @phpstan-param array{ + * echo?: bool, + * aria_label?: string, + * } $args */ function get_search_form($args = array()) { @@ -97096,6 +98556,22 @@ function wp_registration_url() * * } * @return void|string Void if 'echo' argument is true, login form HTML if 'echo' is false. + * @phpstan-param array{ + * echo?: bool, + * redirect?: string, + * form_id?: string, + * label_username?: string, + * label_password?: string, + * label_remember?: string, + * label_log_in?: string, + * id_username?: string, + * id_password?: string, + * id_remember?: string, + * id_submit?: string, + * remember?: bool, + * value_username?: string, + * value_remember?: bool, + * } $args */ function wp_login_form($args = array()) { @@ -97565,6 +99041,21 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after = * @type string $w Week. Default current week. * } * @return void|string Void if 'echo' argument is true, archive links if 'echo' is false. + * @phpstan-param array{ + * type?: string, + * limit?: string|int, + * format?: string, + * before?: string, + * after?: string, + * show_post_count?: bool, + * echo?: bool|int, + * order?: string, + * post_type?: string, + * year?: string, + * monthnum?: string, + * day?: string, + * w?: string, + * } $args */ function wp_get_archives($args = '') { @@ -98062,6 +99553,16 @@ function wp_enqueue_editor() * @type array $htmlhint HTMLHint rule overrides. * } * @return array|false Settings for the enqueued code editor, or false if the editor was not enqueued. + * @phpstan-param array{ + * type?: string, + * file?: string, + * theme?: WP_Theme, + * plugin?: string, + * codemirror?: array, + * csslint?: array, + * jshint?: array, + * htmlhint?: array, + * } $args */ function wp_enqueue_code_editor($args) { @@ -98086,6 +99587,16 @@ function wp_enqueue_code_editor($args) * @type array $htmlhint HTMLHint rule overrides. * } * @return array|false Settings for the code editor. + * @phpstan-param array{ + * type?: string, + * file?: string, + * theme?: WP_Theme, + * plugin?: string, + * codemirror?: array, + * csslint?: array, + * jshint?: array, + * htmlhint?: array, + * } $args */ function wp_get_code_editor_settings($args) { @@ -98221,6 +99732,24 @@ function language_attributes($doctype = 'html') * } * @return string|array|void String of page links or array of page links, depending on 'type' argument. * Void if total number of pages is less than 2. + * @phpstan-param array{ + * base?: string, + * format?: string, + * total?: int, + * current?: int, + * aria_current?: string, + * show_all?: bool, + * end_size?: int, + * mid_size?: int, + * prev_next?: bool, + * prev_text?: bool, + * next_text?: bool, + * type?: string, + * add_args?: array, + * add_fragment?: string, + * before_page_number?: string, + * after_page_number?: string, + * } $args */ function paginate_links($args = '') { @@ -98250,6 +99779,11 @@ function paginate_links($args = '') * @type string $focus SVG icon color on focus. * @type string $current SVG icon color of current admin menu link. * } + * @phpstan-param array{ + * base?: string, + * focus?: string, + * current?: string, + * } $icons */ function wp_admin_css_color($key, $name, $url, $colors = array(), $icons = array()) { @@ -98564,6 +100098,7 @@ function wp_safe_remote_head($url, $args = array()) * @type WP_HTTP_Cookie[] $cookies Array of response cookies. * @type WP_HTTP_Requests_Response|null $http_response Raw HTTP response object. * } + * boop */ function wp_remote_request($url, $args = array()) { @@ -100062,6 +101597,7 @@ function _nx($single, $plural, $number, $context, $domain = 'default') * @type null $context Context information for the translators. * @type string $domain Text domain. * } + * boop */ function _n_noop($singular, $plural, $domain = \null) { @@ -100100,6 +101636,7 @@ function _n_noop($singular, $plural, $domain = \null) * @type string $context Context information for the translators. * @type string $domain Text domain. * } + * boop */ function _nx_noop($singular, $plural, $context, $domain = \null) { @@ -100452,6 +101989,17 @@ function wp_get_pomo_file_data($po_file) * @type bool $show_option_en_us Whether to show an option for English (United States). Default true. * } * @return string HTML dropdown list of languages. + * @phpstan-param array{ + * id?: string, + * name?: string, + * languages?: array, + * translations?: array, + * selected?: string, + * echo?: bool|int, + * show_available_translations?: bool, + * show_option_site_default?: bool, + * show_option_en_us?: bool, + * } $args */ function wp_dropdown_languages($args = array()) { @@ -101465,6 +103013,11 @@ function previous_posts_link($label = \null) * Default 'Next Page »'. * } * @return string The posts link navigation. + * @phpstan-param array{ + * sep?: string, + * prelabel?: string, + * nxtlabel?: string, + * } $args */ function get_posts_nav_link($args = array()) { @@ -101502,6 +103055,16 @@ function posts_nav_link($sep = '', $prelabel = '', $nxtlabel = '') * @type string $class Custom class for the nav element. Default 'post-navigation'. * } * @return string Markup for post links. + * @phpstan-param array{ + * prev_text?: string, + * next_text?: string, + * in_same_term?: bool, + * excluded_terms?: int[]|string, + * taxonomy?: string, + * screen_reader_text?: string, + * aria_label?: string, + * class?: string, + * } $args */ function get_the_post_navigation($args = array()) { @@ -101539,6 +103102,13 @@ function the_post_navigation($args = array()) * @type string $class Custom class for the nav element. Default 'posts-navigation'. * } * @return string Markup for posts links. + * @phpstan-param array{ + * prev_text?: string, + * next_text?: string, + * screen_reader_text?: string, + * aria_label?: string, + * class?: string, + * } $args */ function get_the_posts_navigation($args = array()) { @@ -101570,6 +103140,11 @@ function the_posts_navigation($args = array()) * @type string $class Custom class for the nav element. Default 'pagination'. * } * @return string Markup for pagination links. + * @phpstan-param array{ + * screen_reader_text?: string, + * aria_label?: string, + * class?: string, + * } $args */ function get_the_posts_pagination($args = array()) { @@ -101700,6 +103275,13 @@ function paginate_comments_links($args = array()) * @type string $class Custom class for the nav element. Default 'comment-navigation'. * } * @return string Markup for comments links. + * @phpstan-param array{ + * prev_text?: string, + * next_text?: string, + * screen_reader_text?: string, + * aria_label?: string, + * class?: string, + * } $args */ function get_the_comments_navigation($args = array()) { @@ -101731,6 +103313,11 @@ function the_comments_navigation($args = array()) * @type string $class Custom class for the nav element. Default 'comments-pagination'. * } * @return string Markup for pagination links. + * @phpstan-param array{ + * screen_reader_text?: string, + * aria_label?: string, + * class?: string, + * } $args */ function get_the_comments_pagination($args = array()) { @@ -102117,6 +103704,14 @@ function the_shortlink($text = '', $title = '', $before = '', $after = '') * plus a "found_avatar" guess. Pass as a reference. Default null. * } * @return string|false The URL of the avatar on success, false on failure. + * @phpstan-param array{ + * size?: int, + * default?: string, + * force_default?: bool, + * rating?: string, + * scheme?: string, + * processed_args?: array, + * } $args */ function get_avatar_url($id_or_email, $args = \null) { @@ -102167,6 +103762,18 @@ function is_avatar_comment_type($comment_type) * false or not set if we couldn't. * @type string $url The URL of the avatar we found. * } + * @phpstan-param array{ + * size?: int, + * height?: int, + * width?: int, + * default?: string, + * force_default?: bool, + * rating?: string, + * scheme?: string, + * processed_args?: array, + * extra_attr?: string, + * } $args + * boop */ function get_avatar_data($id_or_email, $args = \null) { @@ -103067,6 +104674,7 @@ function wp_get_additional_image_sizes() * @type int $0 The maximum width in pixels. * @type int $1 The maximum height in pixels. * } + * boop */ function image_constrain_size_for_editor($width, $height, $size = 'medium', $context = \null) { @@ -103115,6 +104723,7 @@ function image_hwstring($width, $height) * @type int $2 Image height in pixels. * @type bool $3 Whether the image is a resized image. * } + * boop */ function image_downsize($id, $size = 'medium') { @@ -103221,6 +104830,7 @@ function get_image_tag($id, $alt, $title, $align, $size = 'medium') * @type int $0 The width in pixels. * @type int $1 The height in pixels. * } + * boop */ function wp_constrain_dimensions($current_width, $current_height, $max_width = 0, $max_height = 0) { @@ -103319,6 +104929,7 @@ function wp_image_matches_ratio($source_width, $source_height, $target_width, $t * @type string $path Absolute filesystem path of image. * @type string $url URL of image. * } + * boop */ function image_get_intermediate_size($post_id, $size = 'thumbnail') { @@ -103362,6 +104973,7 @@ function wp_get_registered_image_subsizes() * @type int $2 Image height in pixels. * @type bool $3 Whether the image is a resized image. * } + * boop */ function wp_get_attachment_image_src($attachment_id, $size = 'thumbnail', $icon = \false) { @@ -103397,6 +105009,14 @@ function wp_get_attachment_image_src($attachment_id, $size = 'thumbnail', $icon * Defaults to 'lazy', depending on wp_lazy_loading_enabled(). * } * @return string HTML img element or empty string on failure. + * @phpstan-param array{ + * src?: string, + * class?: string, + * alt?: string, + * srcset?: string, + * sizes?: string, + * loading?: string|false, + * } $attr */ function wp_get_attachment_image($attachment_id, $size = 'thumbnail', $icon = \false, $attr = '') { @@ -103444,6 +105064,7 @@ function _wp_get_attachment_relative_path($file) * @type int $0 Image width. * @type int $1 Image height. * } + * boop */ function _wp_get_image_size_from_meta($size_name, $image_meta) { @@ -103480,6 +105101,10 @@ function wp_get_attachment_image_srcset($attachment_id, $size = 'medium', $image * @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'. * @param int $attachment_id Optional. The image attachment ID. Default 0. * @return string|false The 'srcset' attribute value. False on error or when only one source exists. + * @phpstan-param array{ + * 0?: int, + * 1?: int, + * } $size_array */ function wp_calculate_image_srcset($size_array, $image_src, $image_meta, $attachment_id = 0) { @@ -103721,6 +105346,14 @@ function _wp_post_thumbnail_class_filter_remove($attr) * } * @param string $content Shortcode content. * @return string HTML content to display the caption. + * @phpstan-param array{ + * id?: string, + * caption_id?: string, + * align?: string, + * width?: int, + * caption?: string, + * class?: string, + * } $attr */ function img_caption_shortcode($attr, $content = \null) { @@ -103756,6 +105389,20 @@ function img_caption_shortcode($attr, $content = \null) * Accepts 'file', 'none'. * } * @return string HTML content to display gallery. + * @phpstan-param array{ + * order?: string, + * orderby?: string, + * id?: int, + * itemtag?: string, + * icontag?: string, + * captiontag?: string, + * columns?: int, + * size?: string|int[], + * ids?: string, + * include?: string, + * exclude?: string, + * link?: string, + * } $attr */ function gallery_shortcode($attr) { @@ -103813,6 +105460,19 @@ function wp_playlist_scripts($type) * } * * @return string Playlist output. Empty string if the passed type is unsupported. + * @phpstan-param array{ + * type?: string, + * order?: string, + * orderby?: string, + * id?: int, + * ids?: array, + * exclude?: array, + * style?: string, + * tracklist?: bool, + * tracknumbers?: bool, + * images?: bool, + * artists?: bool, + * } $attr */ function wp_playlist_shortcode($attr) { @@ -103870,6 +105530,14 @@ function wp_get_attachment_id3_keys($attachment, $context = 'display') * } * @param string $content Shortcode content. * @return string|void HTML content to display audio. + * @phpstan-param array{ + * src?: string, + * loop?: string, + * autoplay?: string, + * preload?: string, + * class?: string, + * style?: string, + * } $attr */ function wp_audio_shortcode($attr, $content = '') { @@ -103910,6 +105578,16 @@ function wp_get_video_extensions() * } * @param string $content Shortcode content. * @return string|void HTML content to display video. + * @phpstan-param array{ + * src?: string, + * height?: int, + * width?: int, + * poster?: string, + * loop?: string, + * autoplay?: string, + * preload?: string, + * class?: string, + * } $attr */ function wp_video_shortcode($attr, $content = '') { @@ -104078,6 +105756,7 @@ function wp_imagecreatetruecolor($width, $height) * @type int $0 The maximum width in pixels. * @type int $1 The maximum height in pixels. * } + * boop */ function wp_expand_dimensions($example_width, $example_height, $max_width, $max_height) { @@ -104187,6 +105866,7 @@ function wp_plupload_default_settings() * @type int $width If the attachment is an image, represents the width of the image in pixels. * } * + * boop */ function wp_prepare_attachment_for_js($attachment) { @@ -104395,6 +106075,7 @@ function wp_getimagesize($filename, array &$image_info = \null) * @type string|false $type The WebP type: one of 'lossy', 'lossless' or 'animated-alpha'. * False on failure. * } + * boop */ function wp_get_webp_info($filename) { @@ -104586,6 +106267,7 @@ function metadata_exists($meta_type, $object_id, $meta_key) * @type string $term_id Optional. The object ID when the meta type is 'term'. * @type string $user_id Optional. The object ID when the meta type is 'user'. * } + * boop */ function get_metadata_by_mid($meta_type, $meta_id) { @@ -104754,6 +106436,16 @@ function sanitize_meta($meta_key, $meta_value, $object_type, $object_subtype = ' * @return bool True if the meta key was successfully registered in the global array, false if not. * Registering a meta key with distinct sanitize and auth callbacks will fire those callbacks, * but will not add to the global registry. + * @phpstan-param array{ + * object_subtype?: string, + * type?: string, + * description?: string, + * single?: bool, + * default?: mixed, + * sanitize_callback?: callable, + * auth_callback?: callable, + * show_in_rest?: bool|array, + * } $args */ function register_meta($object_type, $meta_key, $args, $deprecated = \null) { @@ -105229,6 +106921,7 @@ function _update_posts_count_on_transition_post_status($new_status, $old_status, * @type int $spam The number of spam sites. * @type int $deleted The number of deleted sites. * } + * boop */ function wp_count_sites($network_id = \null) { @@ -105537,6 +107230,16 @@ function get_admin_users_for_domain($domain = '', $path = '') * } * @return array[] An empty array if the installation is considered "large" via wp_is_large_network(). Otherwise, * an associative array of WP_Site data as arrays. + * @phpstan-param array{ + * network_id?: int|int[], + * public?: int, + * archived?: int, + * mature?: int, + * spam?: int, + * deleted?: int, + * limit?: int, + * offset?: int, + * } $args */ function wp_get_sites($args = array()) { @@ -105650,6 +107353,7 @@ function update_user_status($id, $pref, $value, $deprecated = \null) * @type int $blogs Number of sites on the network. * @type int $users Number of users on the network. * } + * boop */ function get_sitestats() { @@ -105829,6 +107533,7 @@ function is_email_address_unsafe($user_email) * @type string $user_email User email address. * @type WP_Error $errors WP_Error object containing any errors found. * } + * boop */ function wpmu_validate_user_signup($user_name, $user_email) { @@ -105865,6 +107570,7 @@ function wpmu_validate_user_signup($user_name, $user_email) * @type string|WP_User $user By default, an empty string. A user object if provided. * @type WP_Error $errors WP_Error containing any errors found. * } + * boop */ function wpmu_validate_blog_signup($blogname, $blog_title, $user = '') { @@ -106248,6 +107954,7 @@ function global_terms($term_id, $deprecated = '') * * @type string $0 The current site's domain. * } + * boop */ function redirect_this_site($deprecated = '') { @@ -106317,6 +108024,10 @@ function maybe_add_existing_user_to_blog() * } * @return true|WP_Error|void True on success or a WP_Error object if the user doesn't exist * or could not be added. Void if $details array was not provided. + * @phpstan-param false|array{ + * user_id?: int, + * role?: string, + * } $details */ function add_existing_user_to_blog($details = \false) { @@ -106891,6 +108602,23 @@ function _prime_network_caches($network_ids) * Passed to the `wp_initialize_site` hook. * } * @return int|WP_Error The new site's ID on success, or error object on failure. + * @phpstan-param array{ + * domain?: string, + * path?: string, + * network_id?: int, + * registered?: string, + * last_updated?: string, + * public?: int, + * archived?: int, + * mature?: int, + * spam?: int, + * deleted?: int, + * lang_id?: int, + * user_id?: int, + * title?: string, + * options?: array, + * meta?: array, + * } $data */ function wp_insert_site(array $data) { @@ -107061,6 +108789,12 @@ function wp_validate_site_data($errors, $data, $old_site = \null) * Default empty array. * } * @return true|WP_Error True on success, or error object on failure. + * @phpstan-param array{ + * user_id?: int, + * title?: string, + * options?: array, + * meta?: array, + * } $args */ function wp_initialize_site($site_id, array $args = array()) { @@ -107304,6 +109038,26 @@ function wp_check_site_meta_support_prefilter($check) * } * @return void|string|false Void if 'echo' argument is true, menu output if 'echo' is false. * False if there are no items or no menu was found. + * @phpstan-param array{ + * menu?: int|string|WP_Term, + * menu_class?: string, + * menu_id?: string, + * container?: string, + * container_class?: string, + * container_id?: string, + * container_aria_label?: string, + * fallback_cb?: callable|false, + * before?: string, + * after?: string, + * link_before?: string, + * link_after?: string, + * echo?: bool, + * depth?: int, + * walker?: object, + * theme_location?: string, + * items_wrap?: string, + * item_spacing?: string, + * } $args */ function wp_nav_menu($args = array()) { @@ -107583,6 +109337,15 @@ function _is_valid_nav_menu_item($item) * @type bool $nopaging Whether to retrieve all menu items (true) or paginate (false). Default true. * } * @return array|false Array of menu items, otherwise false. + * @phpstan-param array{ + * order?: string, + * orderby?: string, + * post_type?: string, + * post_status?: string, + * output?: string, + * output_key?: string, + * nopaging?: bool, + * } $args */ function wp_get_nav_menu_items($menu, $args = array()) { @@ -108259,6 +110022,13 @@ function register_initial_settings() * array with a 'schema' key. * @type mixed $default Default value when calling `get_option()`. * } + * @phpstan-param array{ + * type?: string, + * description?: string, + * sanitize_callback?: callable, + * show_in_rest?: bool|array, + * default?: mixed, + * } $args */ function register_setting($option_group, $option_name, $args = array()) { @@ -109080,6 +110850,17 @@ function wp_set_password($password, $user_id) * @type string $extra_attr HTML attributes to insert in the IMG element. Is not sanitized. Default empty. * } * @return string|false `` tag for the user's avatar. False on failure. + * @phpstan-param array{ + * height?: int, + * width?: int, + * force_default?: bool, + * rating?: string, + * scheme?: string, + * class?: array|string, + * force_display?: bool, + * loading?: string, + * extra_attr?: string, + * } $args */ function get_avatar($id_or_email, $size = 96, $default = '', $alt = '', $args = \null) { @@ -109112,6 +110893,12 @@ function get_avatar($id_or_email, $size = 96, $default = '', $alt = '', $args = * un-split view (single column). Default true. * } * @return string Empty string if strings are equivalent or HTML with differences. + * @phpstan-param array{ + * title?: string, + * title_left?: string, + * title_right?: string, + * show_split_view?: bool, + * } $args */ function wp_text_diff($left_string, $right_string, $args = \null) { @@ -109945,6 +111732,12 @@ function the_title($before = '', $after = '', $echo = \true) * @type WP_Post $post Current post object to retrieve the title for. * } * @return void|string Void if 'echo' argument is true, the title attribute if 'echo' is false. + * @phpstan-param array{ + * before?: string, + * after?: string, + * echo?: bool, + * post?: WP_Post, + * } $args */ function the_title_attribute($args = '') { @@ -110170,6 +111963,19 @@ function post_password_required($post = \null) * @type int|bool $echo Whether to echo or not. Accepts 1|true or 0|false. Default 1|true. * } * @return string Formatted output in HTML. + * @phpstan-param array{ + * before?: string, + * after?: string, + * link_before?: string, + * link_after?: string, + * aria_current?: string, + * next_or_number?: string, + * separator?: string, + * nextpagelink?: string, + * previouspagelink?: string, + * pagelink?: string, + * echo?: int|bool, + * } $args */ function wp_link_pages($args = '') { @@ -110245,6 +112051,19 @@ function the_meta() * elements. Accepts any valid post field. Default 'ID'. * } * @return string HTML dropdown list of pages. + * @phpstan-param array{ + * depth?: int, + * child_of?: int, + * selected?: int|string, + * echo?: bool|int, + * name?: string, + * id?: string, + * class?: string, + * show_option_none?: string, + * show_option_no_change?: string, + * option_none_value?: string, + * value_field?: string, + * } $args */ function wp_dropdown_pages($args = '') { @@ -110288,6 +112107,24 @@ function wp_dropdown_pages($args = '') * @type Walker $walker Walker instance to use for listing pages. Default empty (Walker_Page). * } * @return void|string Void if 'echo' argument is true, HTML list of pages if 'echo' is false. + * @phpstan-param array{ + * child_of?: int, + * authors?: string, + * date_format?: string, + * depth?: int, + * echo?: bool, + * exclude?: string, + * include?: array, + * link_after?: string, + * link_before?: string, + * post_type?: string, + * post_status?: string|array, + * show_date?: string, + * sort_column?: string, + * title_li?: string, + * item_spacing?: string, + * walker?: Walker, + * } $args */ function wp_list_pages($args = '') { @@ -110323,6 +112160,20 @@ function wp_list_pages($args = '') * @type Walker $walker Walker instance to use for listing pages. Default empty (Walker_Page). * } * @return void|string Void if 'echo' argument is true, HTML menu if 'echo' is false. + * @phpstan-param array{ + * sort_column?: string, + * menu_id?: string, + * menu_class?: string, + * container?: string, + * echo?: bool, + * show_home?: int|bool|string, + * link_before?: string, + * link_after?: string, + * before?: string, + * after?: string, + * item_spacing?: string, + * walker?: Walker, + * } $args */ function wp_page_menu($args = array()) { @@ -110801,6 +112652,7 @@ function get_children($args = '', $output = \OBJECT) * @type string $extended Content after the more tag. * @type string $more_text Custom read more text, or empty string. * } + * boop */ function get_extended($post) { @@ -110974,6 +112826,20 @@ function _wp_privacy_statuses() * Default to false. * } * @return object + * @phpstan-param array{ + * label?: bool|string, + * label_count?: bool|array, + * exclude_from_search?: bool, + * _builtin?: bool, + * public?: bool, + * internal?: bool, + * protected?: bool, + * private?: bool, + * publicly_queryable?: bool, + * show_in_admin_all_list?: bool, + * show_in_admin_status_list?: bool, + * date_floating?: bool, + * } $args */ function register_post_status($post_status, $args = array()) { @@ -111246,6 +113112,39 @@ function get_post_types($args = array(), $output = 'names', $operator = 'and') * } * @return WP_Post_Type|WP_Error The registered post type object on success, * WP_Error object on failure. + * @phpstan-param array{ + * label?: string, + * labels?: string[], + * description?: string, + * public?: bool, + * hierarchical?: bool, + * exclude_from_search?: bool, + * publicly_queryable?: bool, + * show_ui?: bool, + * show_in_menu?: bool|string, + * show_in_nav_menus?: bool, + * show_in_admin_bar?: bool, + * show_in_rest?: bool, + * rest_base?: string, + * rest_controller_class?: string, + * menu_position?: int, + * menu_icon?: string, + * capability_type?: string, + * capabilities?: string[], + * map_meta_cap?: bool, + * supports?: array, + * register_meta_box_cb?: callable, + * taxonomies?: string[], + * has_archive?: bool|string, + * rewrite?: bool|array, + * query_var?: string|bool, + * can_export?: bool, + * delete_with_user?: bool, + * template?: array, + * template_lock?: string|false, + * _builtin?: bool, + * _edit_link?: string, + * } $args */ function register_post_type($post_type, $args = array()) { @@ -111624,6 +113523,13 @@ function is_post_publicly_viewable($post = \null) * @type bool $suppress_filters Whether to suppress filters. Default true. * } * @return WP_Post[]|int[] Array of post objects or post IDs. + * @phpstan-param array{ + * numberposts?: int, + * category?: int|string, + * include?: int[], + * exclude?: int[], + * suppress_filters?: bool, + * } $args */ function get_posts($args = \null) { @@ -112121,6 +114027,9 @@ function wp_get_post_tags($post_id = 0, $args = array()) * } * @return array|WP_Error Array of WP_Term objects on success or empty array if no terms were found. * WP_Error object if `$taxonomy` doesn't exist. + * @phpstan-param array{ + * fields?: string, + * } $args */ function wp_get_post_terms($post_id = 0, $taxonomy = 'post_tag', $args = array()) { @@ -112206,6 +114115,35 @@ function wp_get_recent_posts($args = array(), $output = \ARRAY_A) * @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false. * @param bool $fire_after_hooks Optional. Whether to fire the after insert hooks. Default true. * @return int|WP_Error The post ID on success. The value 0 or WP_Error on failure. + * @phpstan-param array{ + * ID?: int, + * post_author?: int, + * post_date?: string, + * post_date_gmt?: string, + * post_content?: mixed, + * post_content_filtered?: string, + * post_title?: string, + * post_excerpt?: string, + * post_status?: string, + * post_type?: string, + * comment_status?: string, + * ping_status?: string, + * post_password?: string, + * post_name?: string, + * to_ping?: string, + * pinged?: string, + * post_modified?: string, + * post_modified_gmt?: string, + * post_parent?: int, + * menu_order?: int, + * post_mime_type?: string, + * guid?: string, + * import_id?: int, + * post_category?: int[], + * tags_input?: array, + * tax_input?: array, + * meta_input?: array, + * } $postarr */ function wp_insert_post($postarr, $wp_error = \false, $fire_after_hooks = \true) { @@ -112657,6 +114595,23 @@ function get_page_uri($page = 0) * @return WP_Post[]|int[]|false Array of pages (or hierarchical post type items). Boolean false if the * specified post type is not hierarchical or the specified status is not * supported by the post type. + * @phpstan-param array{ + * child_of?: int, + * sort_order?: string, + * sort_column?: string, + * hierarchical?: bool, + * exclude?: int[], + * include?: int[], + * meta_key?: string, + * meta_value?: string, + * authors?: string, + * parent?: int, + * exclude_tree?: string|int[], + * number?: int, + * offset?: int, + * post_type?: string, + * post_status?: string|array, + * } $args */ function get_pages($args = array()) { @@ -112764,6 +114719,7 @@ function wp_delete_attachment_files($post_id, $meta, $backup_sizes, $file) * 'file', 'width', 'height', and 'mime-type'. * @type array $image_meta Image metadata. * } + * boop */ function wp_get_attachment_metadata($attachment_id = 0, $unfiltered = \false) { @@ -114197,6 +116153,11 @@ function register_rest_route($namespace, $route, $args = array(), $override = \f * @type array|null $schema Optional. The schema for this field. * Default is 'null', no schema entry will be returned. * } + * @phpstan-param array{ + * get_callback?: callable|null, + * update_callback?: callable|null, + * schema?: array|null, + * } $args */ function register_rest_field($object_type, $attribute, $args = array()) { @@ -116869,6 +118830,32 @@ function is_taxonomy_hierarchical($taxonomy) * Default false. * } * @return WP_Taxonomy|WP_Error The registered taxonomy object on success, WP_Error object on failure. + * @phpstan-param array{ + * labels?: string[], + * description?: string, + * public?: bool, + * publicly_queryable?: bool, + * hierarchical?: bool, + * show_ui?: bool, + * show_in_menu?: bool, + * show_in_nav_menus?: bool, + * show_in_rest?: bool, + * rest_base?: string, + * rest_controller_class?: string, + * show_tagcloud?: bool, + * show_in_quick_edit?: bool, + * show_admin_column?: bool, + * meta_box_cb?: bool|callable, + * meta_box_sanitize_cb?: callable, + * capabilities?: string[], + * rewrite?: bool|array, + * query_var?: string|bool, + * update_count_callback?: callable, + * default_term?: string|array, + * sort?: bool, + * args?: array, + * _builtin?: bool, + * } $args */ function register_taxonomy($taxonomy, $object_type, $args = array()) { @@ -116941,6 +118928,7 @@ function unregister_taxonomy($taxonomy) * @type string $item_link_description Used in the block editor. Description for a navigation link block * variation. Default 'A link to a tag'/'A link to a category'. * } + * boop */ function get_taxonomy_labels($tax) { @@ -117497,6 +119485,10 @@ function wp_delete_object_term_relationships($object_id, $taxonomies) * } * @return bool|int|WP_Error True on success, false if term does not exist. Zero on attempted * deletion of default Category. WP_Error if the taxonomy does not exist. + * @phpstan-param array{ + * default?: int, + * force_default?: bool, + * } $args */ function wp_delete_term($term, $taxonomy, $args = array()) { @@ -117578,6 +119570,13 @@ function wp_get_object_terms($object_ids, $taxonomies, $args = array()) * @type int $term_id The new term ID. * @type int|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string. * } + * @phpstan-param array{ + * alias_of?: string, + * description?: string, + * parent?: int, + * slug?: string, + * } $args + * boop */ function wp_insert_term($term, $taxonomy, $args = array()) { @@ -117696,6 +119695,12 @@ function wp_unique_term_slug($slug, $term) * } * @return array|WP_Error An array containing the `term_id` and `term_taxonomy_id`, * WP_Error otherwise. + * @phpstan-param array{ + * alias_of?: string, + * description?: string, + * parent?: int, + * slug?: string, + * } $args */ function wp_update_term($term_id, $taxonomy, $args = array()) { @@ -118107,6 +120112,12 @@ function get_term_link($term, $taxonomy = '') * @type string $sep Separates each taxonomy. Default is a space. * @type string $after Displays after the taxonomies. Default empty string. * } + * @phpstan-param array{ + * post?: int|WP_Post, + * before?: string, + * sep?: string, + * after?: string, + * } $args */ function the_taxonomies($args = array()) { @@ -118129,6 +120140,10 @@ function the_taxonomies($args = array()) * linked to its archive. * } * @return array List of taxonomies. + * @phpstan-param array{ + * template?: string, + * term_template?: string, + * } $args */ function get_the_taxonomies($post = 0, $args = array()) { @@ -118778,6 +120793,11 @@ function wp_enable_block_templates() * are allowed. Default 0, synonymous for the current blog. * } * @return WP_Theme[] Array of WP_Theme objects. + * @phpstan-param array{ + * errors?: mixed, + * allowed?: mixed, + * blog_id?: int, + * } $args */ function wp_get_themes($args = array()) { @@ -119476,6 +121496,10 @@ function wp_get_custom_css($stylesheet = '') * @type string $stylesheet Stylesheet (child theme) to update. Optional, defaults to current theme/stylesheet. * } * @return WP_Post|WP_Error Post on success, error on failure. + * @phpstan-param array{ + * preprocessed?: string, + * stylesheet?: string, + * } $args */ function wp_update_custom_css_post($css, $args = array()) { @@ -119762,6 +121786,12 @@ function require_if_theme_supports($feature, $include) * } * } * @return true|WP_Error True if the theme feature was successfully registered, a WP_Error object if not. + * @phpstan-param array{ + * type?: string, + * variadic?: boolean, + * description?: string, + * show_in_rest?: bool|array, + * } $args */ function register_theme_feature($feature, $args = array()) { @@ -120498,6 +122528,7 @@ function update_user_meta($user_id, $meta_key, $meta_value, $prev_value = '') * @type int $total_users Total number of users on the site. * @type int[] $avail_roles Array of user counts keyed by user role. * } + * boop */ function count_users($strategy = 'time', $site_id = \null) { @@ -120587,6 +122618,29 @@ function setup_userdata($for_user_id = 0) * these roles will not be included in results. Default empty array. * } * @return string HTML dropdown list of users. + * @phpstan-param array{ + * show_option_all?: string, + * show_option_none?: string, + * option_none_value?: int|string, + * hide_if_only_one_author?: string, + * orderby?: string, + * order?: string, + * include?: int[]|string, + * exclude?: int[]|string, + * multi?: bool|int, + * show?: string, + * echo?: int|bool, + * selected?: int, + * include_selected?: bool, + * name?: string, + * id?: string, + * class?: string, + * blog_id?: int, + * who?: string, + * role?: string|array, + * role__in?: string[], + * role__not_in?: string[], + * } $args */ function wp_dropdown_users($args = '') { @@ -120739,6 +122793,30 @@ function validate_username($username) * } * @return int|WP_Error The newly created user's ID or a WP_Error object if the user could not * be created. + * @phpstan-param object|\WP_User|array{ + * ID?: int, + * user_pass?: string, + * user_login?: string, + * user_nicename?: string, + * user_url?: string, + * user_email?: string, + * display_name?: string, + * nickname?: string, + * first_name?: string, + * last_name?: string, + * description?: string, + * rich_editing?: string, + * syntax_highlighting?: string, + * comment_shortcuts?: string, + * admin_color?: string, + * use_ssl?: bool, + * user_registered?: string, + * user_activation_key?: string, + * spam?: bool, + * show_admin_bar_front?: string, + * role?: string, + * locale?: string, + * } $userdata */ function wp_insert_user($userdata) { @@ -121286,6 +123364,10 @@ function unregister_widget($widget) * assigned number for each sidebar. * Default 'Sidebar' for the first sidebar, otherwise 'Sidebar %d'. * } + * @phpstan-param array{ + * id?: string, + * name?: string, + * } $args */ function register_sidebars($number = 1, $args = array()) { @@ -121339,6 +123421,18 @@ function register_sidebars($number = 1, $args = array()) * Default empty string. * } * @return string Sidebar ID added to $wp_registered_sidebars global. + * @phpstan-param array{ + * name?: string, + * id?: string, + * description?: string, + * class?: string, + * before_widget?: string, + * after_widget?: string, + * before_title?: string, + * after_title?: string, + * before_sidebar?: string, + * after_sidebar?: string, + * } $args */ function register_sidebar($args = array()) { @@ -121400,6 +123494,11 @@ function is_registered_sidebar($sidebar_id) * Only available for WP_Widget based widgets. * } * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. + * @phpstan-param array{ + * classname?: string, + * description?: string, + * show_instance_in_rest?: bool, + * } $options */ function wp_register_sidebar_widget($id, $name, $output_callback, $options = array(), ...$params) { @@ -121472,6 +123571,11 @@ function wp_unregister_sidebar_widget($id) * text widget. The widget id will end up looking like `{$id_base}-{$unique_number}`. * } * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. + * @phpstan-param array{ + * height?: int, + * width?: int, + * id_base?: int|string, + * } $options */ function wp_register_widget_control($id, $name, $control_callback, $options = array(), ...$params) { @@ -121689,6 +123793,12 @@ function wp_convert_widget_settings($base_name, $option_name, $settings) * @type string $after_title HTML content that will be appended to the widget's title when displayed. * Default ``. * } + * @phpstan-param array{ + * before_widget?: string, + * after_widget?: string, + * before_title?: string, + * after_title?: string, + * } $args */ function the_widget($widget, $instance = array(), $args = array()) { From adfcbcb80cf579ee296098d27be54aeff4341cf0 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 22:30:13 +0100 Subject: [PATCH 18/35] Remove some duplication. --- visitor.php | 45 +++++++++++++++++++++------------------------ 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/visitor.php b/visitor.php index 5c51733..a2940ae 100644 --- a/visitor.php +++ b/visitor.php @@ -2,6 +2,7 @@ declare(strict_types = 1); +use phpDocumentor\Reflection\DocBlock\Description; use phpDocumentor\Reflection\DocBlock\Tags\Param; use phpDocumentor\Reflection\DocBlock\Tags\Return_; use phpDocumentor\Reflection\Type; @@ -96,30 +97,24 @@ private function addArrayHashNotation(Doc $docComment): ?Doc private function getAdditionFromParam(Param $tag): ?string { - $tagDescription = $tag->getDescription()->__toString(); + $tagDescription = $tag->getDescription(); $tagVariableName = $tag->getVariableName(); $tagVariableType = $tag->getType(); - // Skip if the description doesn't contain at least one correctly - // formatted `@type`, which indicates an array hash. - if (strpos($tagDescription, ' @type') === false) { - return null; - } - // Skip if the parameter variable name or type are missing. if (!$tagVariableName || !$tagVariableType) { return null; } - $tagVariableType = $this->getTypeFromTag($tagVariableType); + $elements = $this->getElementsFromTag($tagDescription); - if ($tagVariableType === null) { + if ($elements === null) { return null; } - $elements = $this->getElementsFromTag($tagDescription); + $tagVariableType = $this->getTypeFromTag($tagVariableType); - if ($elements === null) { + if ($tagVariableType === null) { return null; } @@ -133,29 +128,23 @@ private function getAdditionFromParam(Param $tag): ?string private function getAdditionFromReturn(Return_ $tag): ?string { - $tagDescription = $tag->getDescription()->__toString(); + $tagDescription = $tag->getDescription(); $tagVariableType = $tag->getType(); - // Skip if the description doesn't contain at least one correctly - // formatted `@type`, which indicates an array hash. - if (strpos($tagDescription, ' @type') === false) { - return null; - } - // Skip if the return type is missing. if (!$tagVariableType) { return null; } - $tagVariableType = $this->getTypeFromTag($tagVariableType); + $elements = $this->getElementsFromTag($tagDescription); - if ($tagVariableType === null) { + if ($elements === null) { return null; } - $elements = $this->getElementsFromTag($tagDescription); + $tagVariableType = $this->getTypeFromTag($tagVariableType); - if ($elements === null) { + if ($tagVariableType === null) { return null; } @@ -185,10 +174,18 @@ private function getTypeFromTag(Type $tagVariableType): ?string return $tagVariableType; } - private function getElementsFromTag(string $tagDescription): ?array + private function getElementsFromTag(Description $tagDescription): ?array { + $text = $tagDescription->__toString(); + + // Skip if the description doesn't contain at least one correctly + // formatted `@type`, which indicates an array hash. + if (strpos($text, ' @type') === false) { + return null; + } + // Populate `$types` with the value of each top level `@type`. - $types = preg_split('/\R+ @type /', $tagDescription); + $types = preg_split('/\R+ @type /', $text); unset($types[0]); $elements = []; From 10667448384f2c5ef6ec3df6f82204afccbc337e Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 22:45:09 +0100 Subject: [PATCH 19/35] This isn't needed. --- visitor.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index a2940ae..a3c403e 100644 --- a/visitor.php +++ b/visitor.php @@ -150,7 +150,7 @@ private function getAdditionFromReturn(Return_ $tag): ?string return sprintf( " * @phpstan-return %1\$s{\n * %2\$s,\n * }", - str_replace(['|string', 'string|'], '', $tagVariableType), + $tagVariableType, implode(",\n * ", $elements) ); } From 7dfacf52df9452dfca70df55f01b879a15306d53 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 22:54:39 +0100 Subject: [PATCH 20/35] Naming. --- visitor.php | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/visitor.php b/visitor.php index a3c403e..5ccd5d3 100644 --- a/visitor.php +++ b/visitor.php @@ -106,13 +106,13 @@ private function getAdditionFromParam(Param $tag): ?string return null; } - $elements = $this->getElementsFromTag($tagDescription); + $elements = $this->getElementsFromDescription($tagDescription); if ($elements === null) { return null; } - $tagVariableType = $this->getTypeFromTag($tagVariableType); + $tagVariableType = $this->getTypeNameFromType($tagVariableType); if ($tagVariableType === null) { return null; @@ -136,13 +136,13 @@ private function getAdditionFromReturn(Return_ $tag): ?string return null; } - $elements = $this->getElementsFromTag($tagDescription); + $elements = $this->getElementsFromDescription($tagDescription); if ($elements === null) { return null; } - $tagVariableType = $this->getTypeFromTag($tagVariableType); + $tagVariableType = $this->getTypeNameFromType($tagVariableType); if ($tagVariableType === null) { return null; @@ -155,7 +155,7 @@ private function getAdditionFromReturn(Return_ $tag): ?string ); } - private function getTypeFromTag(Type $tagVariableType): ?string + private function getTypeNameFromType(Type $tagVariableType): ?string { // PHPStan dosn't support typed array shapes (`int[]{...}`) so replace // typed arrays such as `int[]` with `array`. @@ -174,7 +174,10 @@ private function getTypeFromTag(Type $tagVariableType): ?string return $tagVariableType; } - private function getElementsFromTag(Description $tagDescription): ?array + /** + * @return ?string[] + */ + private function getElementsFromDescription(Description $tagDescription): ?array { $text = $tagDescription->__toString(); From 8dff3b0b928512dbc3fb746a30ae58b22ebba8f8 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 23:00:33 +0100 Subject: [PATCH 21/35] Add an explanation for this. --- visitor.php | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index 5ccd5d3..6a8ae6c 100644 --- a/visitor.php +++ b/visitor.php @@ -118,9 +118,13 @@ private function getAdditionFromParam(Param $tag): ?string return null; } + // It's common for an args parameter to accept a query var string or array with `string|array`. + // Remove the accepted string type for these so we get the strongest typing we can manage. + $tagVariableType = str_replace(['|string', 'string|'], '', $tagVariableType); + return sprintf( " * @phpstan-param %1\$s{\n * %2\$s,\n * } $%3\$s", - str_replace(['|string', 'string|'], '', $tagVariableType), + $tagVariableType, implode(",\n * ", $elements), $tagVariableName ); From c7f4c6e1cae2091ca47bb1536cfd63282a7ce9b5 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 23:02:35 +0100 Subject: [PATCH 22/35] Update stubs. --- wordpress-stubs.php | 470 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 402 insertions(+), 68 deletions(-) diff --git a/wordpress-stubs.php b/wordpress-stubs.php index a5632e2..4277310 100644 --- a/wordpress-stubs.php +++ b/wordpress-stubs.php @@ -5952,7 +5952,18 @@ public function rmdir($path, $recursive = \false) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } - * boop + * @phpstan-return false|array{ + * name?: string, + * perms?: string, + * permsn?: int, + * owner?: string, + * size?: int, + * lastmodunix?: int, + * lastmod?: mixed, + * time?: int, + * type?: string, + * files?: mixed, + * } */ public function dirlist($path, $include_hidden = \true, $recursive = \false) { @@ -6322,7 +6333,18 @@ public function rmdir($path, $recursive = \false) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } - * boop + * @phpstan-return false|array{ + * name?: string, + * perms?: string, + * permsn?: int, + * owner?: string, + * size?: int, + * lastmodunix?: int, + * lastmod?: mixed, + * time?: int, + * type?: string, + * files?: mixed, + * } */ public function dirlist($path, $include_hidden = \true, $recursive = \false) { @@ -6685,7 +6707,18 @@ public function parselisting($line) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } - * boop + * @phpstan-return false|array{ + * name?: string, + * perms?: string, + * permsn?: int, + * owner?: string, + * size?: int, + * lastmodunix?: int, + * lastmod?: mixed, + * time?: int, + * type?: string, + * files?: mixed, + * } */ public function dirlist($path = '.', $include_hidden = \true, $recursive = \false) { @@ -7049,7 +7082,18 @@ public function rmdir($path, $recursive = \false) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } - * boop + * @phpstan-return false|array{ + * name?: string, + * perms?: string, + * permsn?: int, + * owner?: string, + * size?: int, + * lastmodunix?: int, + * lastmod?: mixed, + * time?: int, + * type?: string, + * files?: mixed, + * } */ public function dirlist($path = '.', $include_hidden = \true, $recursive = \false) { @@ -7498,7 +7542,18 @@ public function rmdir($path, $recursive = \false) * @type string $type Type of resource. 'f' for file, 'd' for directory. * @type mixed $files If a directory and $recursive is true, contains another array of files. * } - * boop + * @phpstan-return false|array{ + * name?: string, + * perms?: string, + * permsn?: int, + * owner?: string, + * size?: int, + * lastmodunix?: int, + * lastmod?: mixed, + * time?: int, + * type?: string, + * files?: mixed, + * } */ public function dirlist($path, $include_hidden = \true, $recursive = \false) { @@ -29371,7 +29426,10 @@ public function head($url, $args = array()) * @type string $headers HTTP response headers. * @type string $body HTTP response body. * } - * boop + * @phpstan-return array{ + * headers?: string, + * body?: string, + * } */ public static function processResponse($strResponse) { @@ -29398,7 +29456,11 @@ public static function processResponse($strResponse) * @type WP_Http_Cookie[] $cookies If the original headers contain the 'Set-Cookie' key, * an array containing `WP_Http_Cookie` objects is returned. * } - * boop + * @phpstan-return array{ + * response?: array, + * newheaders?: array, + * cookies?: WP_Http_Cookie[], + * } */ public static function processHeaders($headers, $url = '') { @@ -35256,7 +35318,11 @@ public function set_autofocus($autofocus) * @type string $section ID for section to be autofocused. * @type string $panel ID for panel to be autofocused. * } - * boop + * @phpstan-return array{ + * control?: string, + * section?: string, + * panel?: string, + * } */ public function get_autofocus() { @@ -36536,7 +36602,10 @@ public function __construct($manager, $id, $args = array()) * @type string $base ID base * @type array $keys Keys for multidimensional array. * } - * boop + * @phpstan-return array{ + * base?: string, + * keys?: array, + * } */ public final function id_data() { @@ -37255,7 +37324,10 @@ public function get_widget_control($args) * @type string $control Markup for widget control wrapping form. * @type string $content The contents of the widget form itself. * } - * boop + * @phpstan-return array{ + * control?: string, + * content?: string, + * } */ public function get_widget_control_parts($args) { @@ -38042,7 +38114,10 @@ public function get_sql() * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ protected function get_sql_clauses() { @@ -38064,7 +38139,10 @@ protected function get_sql_clauses() * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ protected function get_sql_for_query($query, $depth = 0) { @@ -38084,7 +38162,10 @@ protected function get_sql_for_query($query, $depth = 0) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ protected function get_sql_for_subquery($query) { @@ -38102,7 +38183,10 @@ protected function get_sql_for_subquery($query) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ protected function get_sql_for_clause($query, $parent_query) { @@ -39591,7 +39675,11 @@ public function getFullHeader() * @type string $path Cookie URL path. * @type string $domain Cookie domain. * } - * boop + * @phpstan-return array{ + * expires?: string|int|null, + * path?: string, + * domain?: string, + * } */ public function get_attributes() { @@ -40577,7 +40665,10 @@ public abstract function stream($mime_type = \null); * @type int $width The image width. * @type int $height The image height. * } - * boop + * @phpstan-return array{ + * width?: int, + * height?: int, + * } */ public function get_size() { @@ -42049,7 +42140,10 @@ public function get_cast_for_type($type = '') * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return false|array{ + * join?: string, + * where?: string, + * } */ public function get_sql($type, $primary_table, $primary_id_column, $context = \null) { @@ -42068,7 +42162,10 @@ public function get_sql($type, $primary_table, $primary_id_column, $context = \n * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ protected function get_sql_clauses() { @@ -42090,7 +42187,10 @@ protected function get_sql_clauses() * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ protected function get_sql_for_query(&$query, $depth = 0) { @@ -42114,7 +42214,10 @@ protected function get_sql_for_query(&$query, $depth = 0) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ public function get_sql_for_clause(&$clause, $parent_query, $clause_key = '') { @@ -46226,7 +46329,10 @@ protected function get_link_ttl() * @type string $slug The extension slug. This is the plugin or theme's directory. * @type string $type The extension type. Either 'plugin' or 'theme'. * } - * boop + * @phpstan-return false|array{ + * slug?: string, + * type?: string, + * } */ protected function get_extension_for_error($error) { @@ -48463,7 +48569,10 @@ protected static function is_first_order_clause($query) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ public function get_sql($primary_table, $primary_id_column) { @@ -48482,7 +48591,10 @@ public function get_sql($primary_table, $primary_id_column) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ protected function get_sql_clauses() { @@ -48504,7 +48616,10 @@ protected function get_sql_clauses() * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ protected function get_sql_for_query(&$query, $depth = 0) { @@ -48524,7 +48639,10 @@ protected function get_sql_for_query(&$query, $depth = 0) * @type string $join SQL fragment to append to the main JOIN clause. * @type string $where SQL fragment to append to the main WHERE clause. * } - * boop + * @phpstan-return array{ + * join?: string, + * where?: string, + * } */ public function get_sql_for_clause(&$clause, $parent_query) { @@ -49595,7 +49713,12 @@ public function _changed($orig, $final) * of `$orig`. A value >= 0 corresponds to index of `$final`. * Value < 0 indicates a blank row. * } - * boop + * @phpstan-return array{ + * orig_matches?: array, + * final_matches?: array, + * orig_rows?: array, + * final_rows?: array, + * } */ public function interleave_changed_lines($orig, $final) { @@ -58192,7 +58315,10 @@ public function __construct(\WP_Customize_Selective_Refresh $component, $id, $ar * @type string $base ID base. * @type array $keys Keys for multidimensional array. * } - * boop + * @phpstan-return array{ + * base?: string, + * keys?: array, + * } */ public final function id_data() { @@ -60756,7 +60882,10 @@ public function serve_request($path = \null) * @type array $_links Links. * @type array $_embedded Embedded objects. * } - * boop + * @phpstan-return array{ + * _links?: array, + * _embedded?: array, + * } */ public function response_to_data($response, $embed) { @@ -60803,7 +60932,10 @@ public static function get_compact_response_links($response) * @type array $_links Links. * @type array $_embedded Embedded objects. * } - * boop + * @phpstan-return array{ + * _links?: array, + * _embedded?: array, + * } */ protected function embed_links($data, $embed = \true) { @@ -69986,7 +70118,10 @@ public function init_charset() * @type string $charset Character set. * @type string $collate Collation. * } - * boop + * @phpstan-return array{ + * charset?: string, + * collate?: string, + * } */ public function determine_charset($charset, $collate) { @@ -76783,7 +76918,12 @@ function display_plugins_table() * @type string $version The most recent version of the plugin. * @type string $file Plugin filename relative to the plugins directory. * } - * boop + * @phpstan-return array{ + * status?: string, + * url?: string, + * version?: string, + * file?: string, + * } */ function install_plugin_install_status($api, $loop = \false) { @@ -76864,7 +77004,20 @@ function install_plugin_information() * @type string $RequiresPHP Minimum required version of PHP. * @type string $UpdateURI ID of the plugin for update purposes, should be a URI. * } - * boop + * @phpstan-return array{ + * Name?: string, + * Title?: string, + * Description?: string, + * Author?: string, + * AuthorURI?: string, + * Version?: string, + * TextDomain?: string, + * DomainPath?: string, + * Network?: bool, + * RequiresWP?: string, + * RequiresPHP?: string, + * UpdateURI?: string, + * } */ function get_plugin_data($plugin_file, $markup = \true, $translate = \true) { @@ -76896,7 +77049,17 @@ function get_plugin_data($plugin_file, $markup = \true, $translate = \true) * @type string $DomainPath Plugins relative directory path to .mo files. * @type bool $Network Whether the plugin can only be activated network-wide. * } - * boop + * @phpstan-return array{ + * Name?: string, + * Title?: string, + * Description?: string, + * Author?: string, + * AuthorURI?: string, + * Version?: string, + * TextDomain?: string, + * DomainPath?: string, + * Network?: bool, + * } */ function _get_plugin_data_markup_translate($plugin_file, $plugin_data, $markup = \true, $translate = \true) { @@ -78122,7 +78285,10 @@ function postbox_classes($box_id, $screen_id) * @type string $0 The permalink with placeholder for the post name. * @type string $1 The post name. * } - * boop + * @phpstan-return array{ + * 0?: string, + * 1?: string, + * } */ function get_sample_permalink($id, $title = \null, $name = \null) { @@ -79424,7 +79590,12 @@ function add_settings_error($setting, $code, $message, $type = 'error') * @type string $type Optional. Message type, controls HTML class. Possible values include 'error', * 'success', 'warning', 'info'. Default 'error'. * } - * boop + * @phpstan-return array{ + * setting?: string, + * code?: string, + * message?: string, + * type?: string, + * } */ function get_settings_errors($setting = '', $sanitize = \false) { @@ -80567,7 +80738,12 @@ function wp_get_auto_update_message() * @type string $password The password of the site owner, if their user account didn't already exist. * @type string $password_message The explanatory message regarding the password. * } - * boop + * @phpstan-return array{ + * url?: string, + * user_id?: int, + * password?: string, + * password_message?: string, + * } */ function wp_install($blog_title, $user_name, $user_email, $public, $deprecated = '', $user_password = '', $language = '') { @@ -87827,7 +88003,6 @@ function wp_check_comment_disallowed_list($author, $email, $url, $comment, $user * @type int $total_comments The total number of non-trashed comments, including spam. * @type int $all The total number of pending or approved comments. * } - * boop */ function wp_count_comments($post_id = 0) { @@ -87962,7 +88137,11 @@ function _clear_modified_cache_on_transition_comment_status($new_status, $old_st * @type string $comment_author_email The email address of the current commenter, or an empty string. * @type string $comment_author_url The URL address of the current commenter, or an empty string. * } - * boop + * @phpstan-return array{ + * comment_author?: string, + * comment_author_email?: string, + * comment_author_url?: string, + * } */ function wp_get_current_commenter() { @@ -91849,7 +92028,10 @@ function wp_embed_unregister_handler($id, $priority = 10) * @type int $0 The embed width. * @type int $1 The embed height. * } - * boop + * @phpstan-return array{ + * 0?: int, + * 1?: int, + * } */ function wp_embed_defaults($url = '') { @@ -95768,7 +95950,14 @@ function wp_get_upload_dir() * @type string $baseurl URL path without subdir. * @type string|false $error False or error message. * } - * boop + * @phpstan-return array{ + * path?: string, + * url?: string, + * subdir?: string, + * basedir?: string, + * baseurl?: string, + * error?: string|false, + * } */ function wp_upload_dir($time = \null, $create_dir = \true, $refresh_cache = \false) { @@ -95862,7 +96051,12 @@ function _wp_check_existing_file_names($filename, $files) * @type string $type File type. * @type string|false $error Error message, if there has been an error. * } - * boop + * @phpstan-return array{ + * file?: string, + * url?: string, + * type?: string, + * error?: string|false, + * } */ function wp_upload_bits($name, $deprecated, $bits, $time = \null) { @@ -95906,7 +96100,10 @@ function wp_get_default_extension_for_mime_type($mime_type) * @type string|false $ext File extension, or false if the file doesn't match a mime type. * @type string|false $type File mime type, or false if the file doesn't match a mime type. * } - * boop + * @phpstan-return array{ + * ext?: string|false, + * type?: string|false, + * } */ function wp_check_filetype($filename, $mimes = \null) { @@ -95934,7 +96131,11 @@ function wp_check_filetype($filename, $mimes = \null) * @type string|false $type File mime type, or false if the file doesn't match a mime type. * @type string|false $proper_filename File name with its correct extension, or false if it cannot be determined. * } - * boop + * @phpstan-return array{ + * ext?: string|false, + * type?: string|false, + * proper_filename?: string|false, + * } */ function wp_check_filetype_and_ext($file, $filename, $mimes = \null) { @@ -96187,7 +96388,11 @@ function _scalar_wp_die_handler($message = '', $title = '', $args = array()) * @type string $1 Error title. * @type array $2 Arguments to control behavior. * } - * boop + * @phpstan-return array{ + * 0?: string, + * 1?: string, + * 2?: array, + * } */ function _wp_die_process_input($message, $title = '', $args = array()) { @@ -100098,7 +100303,13 @@ function wp_safe_remote_head($url, $args = array()) * @type WP_HTTP_Cookie[] $cookies Array of response cookies. * @type WP_HTTP_Requests_Response|null $http_response Raw HTTP response object. * } - * boop + * @phpstan-return \WP_Error|array{ + * headers?: string[], + * body?: string, + * response?: array, + * cookies?: WP_HTTP_Cookie[], + * http_response?: WP_HTTP_Requests_Response|null, + * } */ function wp_remote_request($url, $args = array()) { @@ -101597,7 +101808,14 @@ function _nx($single, $plural, $number, $context, $domain = 'default') * @type null $context Context information for the translators. * @type string $domain Text domain. * } - * boop + * @phpstan-return array{ + * 0?: string, + * 1?: string, + * singular?: string, + * plural?: string, + * context?: null, + * domain?: string, + * } */ function _n_noop($singular, $plural, $domain = \null) { @@ -101636,7 +101854,15 @@ function _n_noop($singular, $plural, $domain = \null) * @type string $context Context information for the translators. * @type string $domain Text domain. * } - * boop + * @phpstan-return array{ + * 0?: string, + * 1?: string, + * 2?: string, + * singular?: string, + * plural?: string, + * context?: string, + * domain?: string, + * } */ function _nx_noop($singular, $plural, $context, $domain = \null) { @@ -103773,7 +103999,10 @@ function is_avatar_comment_type($comment_type) * processed_args?: array, * extra_attr?: string, * } $args - * boop + * @phpstan-return array{ + * found_avatar?: bool, + * url?: string, + * } */ function get_avatar_data($id_or_email, $args = \null) { @@ -104674,7 +104903,10 @@ function wp_get_additional_image_sizes() * @type int $0 The maximum width in pixels. * @type int $1 The maximum height in pixels. * } - * boop + * @phpstan-return array{ + * 0?: int, + * 1?: int, + * } */ function image_constrain_size_for_editor($width, $height, $size = 'medium', $context = \null) { @@ -104723,7 +104955,12 @@ function image_hwstring($width, $height) * @type int $2 Image height in pixels. * @type bool $3 Whether the image is a resized image. * } - * boop + * @phpstan-return false|array{ + * 0?: string, + * 1?: int, + * 2?: int, + * 3?: bool, + * } */ function image_downsize($id, $size = 'medium') { @@ -104830,7 +105067,10 @@ function get_image_tag($id, $alt, $title, $align, $size = 'medium') * @type int $0 The width in pixels. * @type int $1 The height in pixels. * } - * boop + * @phpstan-return array{ + * 0?: int, + * 1?: int, + * } */ function wp_constrain_dimensions($current_width, $current_height, $max_width = 0, $max_height = 0) { @@ -104929,7 +105169,13 @@ function wp_image_matches_ratio($source_width, $source_height, $target_width, $t * @type string $path Absolute filesystem path of image. * @type string $url URL of image. * } - * boop + * @phpstan-return false|array{ + * file?: string, + * width?: int, + * height?: int, + * path?: string, + * url?: string, + * } */ function image_get_intermediate_size($post_id, $size = 'thumbnail') { @@ -104973,7 +105219,12 @@ function wp_get_registered_image_subsizes() * @type int $2 Image height in pixels. * @type bool $3 Whether the image is a resized image. * } - * boop + * @phpstan-return false|array{ + * 0?: string, + * 1?: int, + * 2?: int, + * 3?: bool, + * } */ function wp_get_attachment_image_src($attachment_id, $size = 'thumbnail', $icon = \false) { @@ -105064,7 +105315,10 @@ function _wp_get_attachment_relative_path($file) * @type int $0 Image width. * @type int $1 Image height. * } - * boop + * @phpstan-return false|array{ + * 0?: int, + * 1?: int, + * } */ function _wp_get_image_size_from_meta($size_name, $image_meta) { @@ -105756,7 +106010,10 @@ function wp_imagecreatetruecolor($width, $height) * @type int $0 The maximum width in pixels. * @type int $1 The maximum height in pixels. * } - * boop + * @phpstan-return array{ + * 0?: int, + * 1?: int, + * } */ function wp_expand_dimensions($example_width, $example_height, $max_width, $max_height) { @@ -105866,7 +106123,42 @@ function wp_plupload_default_settings() * @type int $width If the attachment is an image, represents the width of the image in pixels. * } * - * boop + * @phpstan-return void|array{ + * alt?: string, + * author?: string, + * authorName?: string, + * caption?: string, + * compat?: array, + * context?: string, + * date?: int, + * dateFormatted?: string, + * description?: string, + * editLink?: string, + * filename?: string, + * filesizeHumanReadable?: string, + * filesizeInBytes?: int, + * height?: int, + * icon?: string, + * id?: int, + * link?: string, + * menuOrder?: int, + * meta?: array, + * mime?: string, + * modified?: int, + * name?: string, + * nonces?: array, + * orientation?: string, + * sizes?: array, + * status?: string, + * subtype?: string, + * title?: string, + * type?: string, + * uploadedTo?: int, + * uploadedToLink?: string, + * uploadedToTitle?: string, + * url?: string, + * width?: int, + * } */ function wp_prepare_attachment_for_js($attachment) { @@ -106075,7 +106367,11 @@ function wp_getimagesize($filename, array &$image_info = \null) * @type string|false $type The WebP type: one of 'lossy', 'lossless' or 'animated-alpha'. * False on failure. * } - * boop + * @phpstan-return array{ + * width?: int|false, + * height?: int|false, + * type?: string|false, + * } */ function wp_get_webp_info($filename) { @@ -106267,7 +106563,6 @@ function metadata_exists($meta_type, $object_id, $meta_key) * @type string $term_id Optional. The object ID when the meta type is 'term'. * @type string $user_id Optional. The object ID when the meta type is 'user'. * } - * boop */ function get_metadata_by_mid($meta_type, $meta_id) { @@ -106921,7 +107216,14 @@ function _update_posts_count_on_transition_post_status($new_status, $old_status, * @type int $spam The number of spam sites. * @type int $deleted The number of deleted sites. * } - * boop + * @phpstan-return array{ + * all?: int, + * public?: int, + * archived?: int, + * mature?: int, + * spam?: int, + * deleted?: int, + * } */ function wp_count_sites($network_id = \null) { @@ -107353,7 +107655,10 @@ function update_user_status($id, $pref, $value, $deprecated = \null) * @type int $blogs Number of sites on the network. * @type int $users Number of users on the network. * } - * boop + * @phpstan-return array{ + * blogs?: int, + * users?: int, + * } */ function get_sitestats() { @@ -107533,7 +107838,12 @@ function is_email_address_unsafe($user_email) * @type string $user_email User email address. * @type WP_Error $errors WP_Error object containing any errors found. * } - * boop + * @phpstan-return array{ + * user_name?: string, + * orig_username?: string, + * user_email?: string, + * errors?: WP_Error, + * } */ function wpmu_validate_user_signup($user_name, $user_email) { @@ -107570,7 +107880,14 @@ function wpmu_validate_user_signup($user_name, $user_email) * @type string|WP_User $user By default, an empty string. A user object if provided. * @type WP_Error $errors WP_Error containing any errors found. * } - * boop + * @phpstan-return array{ + * domain?: string, + * path?: string, + * blogname?: string, + * blog_title?: string, + * user?: string|WP_User, + * errors?: WP_Error, + * } */ function wpmu_validate_blog_signup($blogname, $blog_title, $user = '') { @@ -107954,7 +108271,9 @@ function global_terms($term_id, $deprecated = '') * * @type string $0 The current site's domain. * } - * boop + * @phpstan-return array{ + * 0?: string, + * } */ function redirect_this_site($deprecated = '') { @@ -112652,7 +112971,11 @@ function get_children($args = '', $output = \OBJECT) * @type string $extended Content after the more tag. * @type string $more_text Custom read more text, or empty string. * } - * boop + * @phpstan-return array{ + * main?: string, + * extended?: string, + * more_text?: string, + * } */ function get_extended($post) { @@ -114719,7 +115042,13 @@ function wp_delete_attachment_files($post_id, $meta, $backup_sizes, $file) * 'file', 'width', 'height', and 'mime-type'. * @type array $image_meta Image metadata. * } - * boop + * @phpstan-return false|array{ + * width?: int, + * height?: int, + * file?: string, + * sizes?: array, + * image_meta?: array, + * } */ function wp_get_attachment_metadata($attachment_id = 0, $unfiltered = \false) { @@ -118928,7 +119257,6 @@ function unregister_taxonomy($taxonomy) * @type string $item_link_description Used in the block editor. Description for a navigation link block * variation. Default 'A link to a tag'/'A link to a category'. * } - * boop */ function get_taxonomy_labels($tax) { @@ -119576,7 +119904,10 @@ function wp_get_object_terms($object_ids, $taxonomies, $args = array()) * parent?: int, * slug?: string, * } $args - * boop + * @phpstan-return \WP_Error|array{ + * term_id?: int, + * term_taxonomy_id?: int|string, + * } */ function wp_insert_term($term, $taxonomy, $args = array()) { @@ -122528,7 +122859,10 @@ function update_user_meta($user_id, $meta_key, $meta_value, $prev_value = '') * @type int $total_users Total number of users on the site. * @type int[] $avail_roles Array of user counts keyed by user role. * } - * boop + * @phpstan-return array{ + * total_users?: int, + * avail_roles?: int[], + * } */ function count_users($strategy = 'time', $site_id = \null) { From 62a1d4bcfb1945461df47292e982b4ea9986d5e5 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 23:08:09 +0100 Subject: [PATCH 23/35] Update the stubs. --- wordpress-stubs.php | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/wordpress-stubs.php b/wordpress-stubs.php index a5d8287..4277310 100644 --- a/wordpress-stubs.php +++ b/wordpress-stubs.php @@ -2676,7 +2676,6 @@ function privDisableMagicQuotes() function privSwapBackMagicQuotes() { } - // -------------------------------------------------------------------------------- } /** * Upgrader API: Plugin_Installer_Skin class @@ -14190,9 +14189,6 @@ public function quicktime_time_to_sample_table($info) public function quicktime_bookmark_time_scale($info) { } - /* - // END helper functions for m4b audiobook chapters - */ } class getid3_riff extends \getid3_handler { @@ -14454,7 +14450,7 @@ class getid3_dts extends \getid3_handler /** * Default DTS syncword used in native .cpt or .dts formats. */ - const syncword = "\xfe\x80\x01"; + const syncword = "þ€\1"; /** * @var int */ @@ -14463,13 +14459,13 @@ class getid3_dts extends \getid3_handler * Possible syncwords indicating bitstream encoding. */ public static $syncwords = array( - 0 => "\xfe\x80\x01", + 0 => "þ€\1", // raw big-endian - 1 => "\xfe\x01\x80", + 1 => "þ\1€", // raw little-endian - 2 => "\x1f\xff\xe8\x00", + 2 => "\37ÿè\0", // 14-bit big-endian - 3 => "\xff\x1f\x00\xe8", + 3 => "ÿ\37\0è", ); // 14-bit little-endian /** @@ -40496,7 +40492,6 @@ public static function test($args = array()) */ class WP_HTTP_Fsockopen extends \WP_HTTP_Streams { - // For backward compatibility for users who are using the class directly. } /** * Base WordPress Image Editor From 5f82c9e45cd33e32f7bee6ec9d57a7849a58f8ff Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 23:35:58 +0100 Subject: [PATCH 24/35] Bump the stubs generator. --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index 4b2489f..0085701 100644 --- a/composer.json +++ b/composer.json @@ -15,7 +15,7 @@ "php": "~7.3 || ~8.0", "phpdocumentor/reflection-docblock": "^5.3", "phpstan/phpstan": "^1.2", - "php-stubs/generator": "^0.7.0", + "php-stubs/generator": "^0.8.0", "nikic/php-parser": "< 4.12.0" }, "suggest": { From 88fa57e032adde84879f97042700944758831392 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 23:36:03 +0100 Subject: [PATCH 25/35] Make this more accurate. --- visitor.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index 6a8ae6c..db173ee 100644 --- a/visitor.php +++ b/visitor.php @@ -187,7 +187,7 @@ private function getElementsFromDescription(Description $tagDescription): ?array // Skip if the description doesn't contain at least one correctly // formatted `@type`, which indicates an array hash. - if (strpos($text, ' @type') === false) { + if (strpos($text, ' @type ') === false) { return null; } From b394261dc2f0d45b57db4cfad3b226cab83b586c Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 23:41:13 +0100 Subject: [PATCH 26/35] Update the stubs again. --- wordpress-stubs.php | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/wordpress-stubs.php b/wordpress-stubs.php index 4277310..a5d8287 100644 --- a/wordpress-stubs.php +++ b/wordpress-stubs.php @@ -2676,6 +2676,7 @@ function privDisableMagicQuotes() function privSwapBackMagicQuotes() { } + // -------------------------------------------------------------------------------- } /** * Upgrader API: Plugin_Installer_Skin class @@ -14189,6 +14190,9 @@ public function quicktime_time_to_sample_table($info) public function quicktime_bookmark_time_scale($info) { } + /* + // END helper functions for m4b audiobook chapters + */ } class getid3_riff extends \getid3_handler { @@ -14450,7 +14454,7 @@ class getid3_dts extends \getid3_handler /** * Default DTS syncword used in native .cpt or .dts formats. */ - const syncword = "þ€\1"; + const syncword = "\xfe\x80\x01"; /** * @var int */ @@ -14459,13 +14463,13 @@ class getid3_dts extends \getid3_handler * Possible syncwords indicating bitstream encoding. */ public static $syncwords = array( - 0 => "þ€\1", + 0 => "\xfe\x80\x01", // raw big-endian - 1 => "þ\1€", + 1 => "\xfe\x01\x80", // raw little-endian - 2 => "\37ÿè\0", + 2 => "\x1f\xff\xe8\x00", // 14-bit big-endian - 3 => "ÿ\37\0è", + 3 => "\xff\x1f\x00\xe8", ); // 14-bit little-endian /** @@ -40492,6 +40496,7 @@ public static function test($args = array()) */ class WP_HTTP_Fsockopen extends \WP_HTTP_Streams { + // For backward compatibility for users who are using the class directly. } /** * Base WordPress Image Editor From d7780d1a656a008b6e42220f9d529b90665121b7 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 23:46:09 +0100 Subject: [PATCH 27/35] Elements in return arrays generally aren't optional. --- visitor.php | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/visitor.php b/visitor.php index db173ee..c41a73f 100644 --- a/visitor.php +++ b/visitor.php @@ -106,7 +106,7 @@ private function getAdditionFromParam(Param $tag): ?string return null; } - $elements = $this->getElementsFromDescription($tagDescription); + $elements = $this->getElementsFromDescription($tagDescription, true); if ($elements === null) { return null; @@ -140,7 +140,7 @@ private function getAdditionFromReturn(Return_ $tag): ?string return null; } - $elements = $this->getElementsFromDescription($tagDescription); + $elements = $this->getElementsFromDescription($tagDescription, false); if ($elements === null) { return null; @@ -181,7 +181,7 @@ private function getTypeNameFromType(Type $tagVariableType): ?string /** * @return ?string[] */ - private function getElementsFromDescription(Description $tagDescription): ?array + private function getElementsFromDescription(Description $tagDescription, bool $optional): ?array { $text = $tagDescription->__toString(); @@ -209,7 +209,12 @@ private function getElementsFromDescription(Description $tagDescription): ?array return null; } - $elements[] = substr($name, 1) . '?: ' . $type; + $elements[] = sprintf( + '%1$s%2$s: %3$s', + substr($name, 1), + $optional ? '?' : '', + $type + ); } return $elements; From 4ddacfbaf5154c6ebfcb4726bebb3b80992562fe Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 23:46:22 +0100 Subject: [PATCH 28/35] Updated stubs. --- wordpress-stubs.php | 544 ++++++++++++++++++++++---------------------- 1 file changed, 272 insertions(+), 272 deletions(-) diff --git a/wordpress-stubs.php b/wordpress-stubs.php index a5d8287..bc600bf 100644 --- a/wordpress-stubs.php +++ b/wordpress-stubs.php @@ -5954,16 +5954,16 @@ public function rmdir($path, $recursive = \false) * @type mixed $files If a directory and $recursive is true, contains another array of files. * } * @phpstan-return false|array{ - * name?: string, - * perms?: string, - * permsn?: int, - * owner?: string, - * size?: int, - * lastmodunix?: int, - * lastmod?: mixed, - * time?: int, - * type?: string, - * files?: mixed, + * name: string, + * perms: string, + * permsn: int, + * owner: string, + * size: int, + * lastmodunix: int, + * lastmod: mixed, + * time: int, + * type: string, + * files: mixed, * } */ public function dirlist($path, $include_hidden = \true, $recursive = \false) @@ -6335,16 +6335,16 @@ public function rmdir($path, $recursive = \false) * @type mixed $files If a directory and $recursive is true, contains another array of files. * } * @phpstan-return false|array{ - * name?: string, - * perms?: string, - * permsn?: int, - * owner?: string, - * size?: int, - * lastmodunix?: int, - * lastmod?: mixed, - * time?: int, - * type?: string, - * files?: mixed, + * name: string, + * perms: string, + * permsn: int, + * owner: string, + * size: int, + * lastmodunix: int, + * lastmod: mixed, + * time: int, + * type: string, + * files: mixed, * } */ public function dirlist($path, $include_hidden = \true, $recursive = \false) @@ -6709,16 +6709,16 @@ public function parselisting($line) * @type mixed $files If a directory and $recursive is true, contains another array of files. * } * @phpstan-return false|array{ - * name?: string, - * perms?: string, - * permsn?: int, - * owner?: string, - * size?: int, - * lastmodunix?: int, - * lastmod?: mixed, - * time?: int, - * type?: string, - * files?: mixed, + * name: string, + * perms: string, + * permsn: int, + * owner: string, + * size: int, + * lastmodunix: int, + * lastmod: mixed, + * time: int, + * type: string, + * files: mixed, * } */ public function dirlist($path = '.', $include_hidden = \true, $recursive = \false) @@ -7084,16 +7084,16 @@ public function rmdir($path, $recursive = \false) * @type mixed $files If a directory and $recursive is true, contains another array of files. * } * @phpstan-return false|array{ - * name?: string, - * perms?: string, - * permsn?: int, - * owner?: string, - * size?: int, - * lastmodunix?: int, - * lastmod?: mixed, - * time?: int, - * type?: string, - * files?: mixed, + * name: string, + * perms: string, + * permsn: int, + * owner: string, + * size: int, + * lastmodunix: int, + * lastmod: mixed, + * time: int, + * type: string, + * files: mixed, * } */ public function dirlist($path = '.', $include_hidden = \true, $recursive = \false) @@ -7544,16 +7544,16 @@ public function rmdir($path, $recursive = \false) * @type mixed $files If a directory and $recursive is true, contains another array of files. * } * @phpstan-return false|array{ - * name?: string, - * perms?: string, - * permsn?: int, - * owner?: string, - * size?: int, - * lastmodunix?: int, - * lastmod?: mixed, - * time?: int, - * type?: string, - * files?: mixed, + * name: string, + * perms: string, + * permsn: int, + * owner: string, + * size: int, + * lastmodunix: int, + * lastmod: mixed, + * time: int, + * type: string, + * files: mixed, * } */ public function dirlist($path, $include_hidden = \true, $recursive = \false) @@ -29431,8 +29431,8 @@ public function head($url, $args = array()) * @type string $body HTTP response body. * } * @phpstan-return array{ - * headers?: string, - * body?: string, + * headers: string, + * body: string, * } */ public static function processResponse($strResponse) @@ -29461,9 +29461,9 @@ public static function processResponse($strResponse) * an array containing `WP_Http_Cookie` objects is returned. * } * @phpstan-return array{ - * response?: array, - * newheaders?: array, - * cookies?: WP_Http_Cookie[], + * response: array, + * newheaders: array, + * cookies: WP_Http_Cookie[], * } */ public static function processHeaders($headers, $url = '') @@ -35323,9 +35323,9 @@ public function set_autofocus($autofocus) * @type string $panel ID for panel to be autofocused. * } * @phpstan-return array{ - * control?: string, - * section?: string, - * panel?: string, + * control: string, + * section: string, + * panel: string, * } */ public function get_autofocus() @@ -36607,8 +36607,8 @@ public function __construct($manager, $id, $args = array()) * @type array $keys Keys for multidimensional array. * } * @phpstan-return array{ - * base?: string, - * keys?: array, + * base: string, + * keys: array, * } */ public final function id_data() @@ -37329,8 +37329,8 @@ public function get_widget_control($args) * @type string $content The contents of the widget form itself. * } * @phpstan-return array{ - * control?: string, - * content?: string, + * control: string, + * content: string, * } */ public function get_widget_control_parts($args) @@ -38119,8 +38119,8 @@ public function get_sql() * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ protected function get_sql_clauses() @@ -38144,8 +38144,8 @@ protected function get_sql_clauses() * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ protected function get_sql_for_query($query, $depth = 0) @@ -38167,8 +38167,8 @@ protected function get_sql_for_query($query, $depth = 0) * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ protected function get_sql_for_subquery($query) @@ -38188,8 +38188,8 @@ protected function get_sql_for_subquery($query) * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ protected function get_sql_for_clause($query, $parent_query) @@ -39680,9 +39680,9 @@ public function getFullHeader() * @type string $domain Cookie domain. * } * @phpstan-return array{ - * expires?: string|int|null, - * path?: string, - * domain?: string, + * expires: string|int|null, + * path: string, + * domain: string, * } */ public function get_attributes() @@ -40671,8 +40671,8 @@ public abstract function stream($mime_type = \null); * @type int $height The image height. * } * @phpstan-return array{ - * width?: int, - * height?: int, + * width: int, + * height: int, * } */ public function get_size() @@ -42146,8 +42146,8 @@ public function get_cast_for_type($type = '') * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return false|array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ public function get_sql($type, $primary_table, $primary_id_column, $context = \null) @@ -42168,8 +42168,8 @@ public function get_sql($type, $primary_table, $primary_id_column, $context = \n * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ protected function get_sql_clauses() @@ -42193,8 +42193,8 @@ protected function get_sql_clauses() * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ protected function get_sql_for_query(&$query, $depth = 0) @@ -42220,8 +42220,8 @@ protected function get_sql_for_query(&$query, $depth = 0) * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ public function get_sql_for_clause(&$clause, $parent_query, $clause_key = '') @@ -46335,8 +46335,8 @@ protected function get_link_ttl() * @type string $type The extension type. Either 'plugin' or 'theme'. * } * @phpstan-return false|array{ - * slug?: string, - * type?: string, + * slug: string, + * type: string, * } */ protected function get_extension_for_error($error) @@ -48575,8 +48575,8 @@ protected static function is_first_order_clause($query) * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ public function get_sql($primary_table, $primary_id_column) @@ -48597,8 +48597,8 @@ public function get_sql($primary_table, $primary_id_column) * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ protected function get_sql_clauses() @@ -48622,8 +48622,8 @@ protected function get_sql_clauses() * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ protected function get_sql_for_query(&$query, $depth = 0) @@ -48645,8 +48645,8 @@ protected function get_sql_for_query(&$query, $depth = 0) * @type string $where SQL fragment to append to the main WHERE clause. * } * @phpstan-return array{ - * join?: string, - * where?: string, + * join: string, + * where: string, * } */ public function get_sql_for_clause(&$clause, $parent_query) @@ -49719,10 +49719,10 @@ public function _changed($orig, $final) * Value < 0 indicates a blank row. * } * @phpstan-return array{ - * orig_matches?: array, - * final_matches?: array, - * orig_rows?: array, - * final_rows?: array, + * orig_matches: array, + * final_matches: array, + * orig_rows: array, + * final_rows: array, * } */ public function interleave_changed_lines($orig, $final) @@ -58321,8 +58321,8 @@ public function __construct(\WP_Customize_Selective_Refresh $component, $id, $ar * @type array $keys Keys for multidimensional array. * } * @phpstan-return array{ - * base?: string, - * keys?: array, + * base: string, + * keys: array, * } */ public final function id_data() @@ -60888,8 +60888,8 @@ public function serve_request($path = \null) * @type array $_embedded Embedded objects. * } * @phpstan-return array{ - * _links?: array, - * _embedded?: array, + * _links: array, + * _embedded: array, * } */ public function response_to_data($response, $embed) @@ -60938,8 +60938,8 @@ public static function get_compact_response_links($response) * @type array $_embedded Embedded objects. * } * @phpstan-return array{ - * _links?: array, - * _embedded?: array, + * _links: array, + * _embedded: array, * } */ protected function embed_links($data, $embed = \true) @@ -70124,8 +70124,8 @@ public function init_charset() * @type string $collate Collation. * } * @phpstan-return array{ - * charset?: string, - * collate?: string, + * charset: string, + * collate: string, * } */ public function determine_charset($charset, $collate) @@ -76924,10 +76924,10 @@ function display_plugins_table() * @type string $file Plugin filename relative to the plugins directory. * } * @phpstan-return array{ - * status?: string, - * url?: string, - * version?: string, - * file?: string, + * status: string, + * url: string, + * version: string, + * file: string, * } */ function install_plugin_install_status($api, $loop = \false) @@ -77010,18 +77010,18 @@ function install_plugin_information() * @type string $UpdateURI ID of the plugin for update purposes, should be a URI. * } * @phpstan-return array{ - * Name?: string, - * Title?: string, - * Description?: string, - * Author?: string, - * AuthorURI?: string, - * Version?: string, - * TextDomain?: string, - * DomainPath?: string, - * Network?: bool, - * RequiresWP?: string, - * RequiresPHP?: string, - * UpdateURI?: string, + * Name: string, + * Title: string, + * Description: string, + * Author: string, + * AuthorURI: string, + * Version: string, + * TextDomain: string, + * DomainPath: string, + * Network: bool, + * RequiresWP: string, + * RequiresPHP: string, + * UpdateURI: string, * } */ function get_plugin_data($plugin_file, $markup = \true, $translate = \true) @@ -77055,15 +77055,15 @@ function get_plugin_data($plugin_file, $markup = \true, $translate = \true) * @type bool $Network Whether the plugin can only be activated network-wide. * } * @phpstan-return array{ - * Name?: string, - * Title?: string, - * Description?: string, - * Author?: string, - * AuthorURI?: string, - * Version?: string, - * TextDomain?: string, - * DomainPath?: string, - * Network?: bool, + * Name: string, + * Title: string, + * Description: string, + * Author: string, + * AuthorURI: string, + * Version: string, + * TextDomain: string, + * DomainPath: string, + * Network: bool, * } */ function _get_plugin_data_markup_translate($plugin_file, $plugin_data, $markup = \true, $translate = \true) @@ -78291,8 +78291,8 @@ function postbox_classes($box_id, $screen_id) * @type string $1 The post name. * } * @phpstan-return array{ - * 0?: string, - * 1?: string, + * 0: string, + * 1: string, * } */ function get_sample_permalink($id, $title = \null, $name = \null) @@ -79596,10 +79596,10 @@ function add_settings_error($setting, $code, $message, $type = 'error') * 'success', 'warning', 'info'. Default 'error'. * } * @phpstan-return array{ - * setting?: string, - * code?: string, - * message?: string, - * type?: string, + * setting: string, + * code: string, + * message: string, + * type: string, * } */ function get_settings_errors($setting = '', $sanitize = \false) @@ -80744,10 +80744,10 @@ function wp_get_auto_update_message() * @type string $password_message The explanatory message regarding the password. * } * @phpstan-return array{ - * url?: string, - * user_id?: int, - * password?: string, - * password_message?: string, + * url: string, + * user_id: int, + * password: string, + * password_message: string, * } */ function wp_install($blog_title, $user_name, $user_email, $public, $deprecated = '', $user_password = '', $language = '') @@ -88143,9 +88143,9 @@ function _clear_modified_cache_on_transition_comment_status($new_status, $old_st * @type string $comment_author_url The URL address of the current commenter, or an empty string. * } * @phpstan-return array{ - * comment_author?: string, - * comment_author_email?: string, - * comment_author_url?: string, + * comment_author: string, + * comment_author_email: string, + * comment_author_url: string, * } */ function wp_get_current_commenter() @@ -92034,8 +92034,8 @@ function wp_embed_unregister_handler($id, $priority = 10) * @type int $1 The embed height. * } * @phpstan-return array{ - * 0?: int, - * 1?: int, + * 0: int, + * 1: int, * } */ function wp_embed_defaults($url = '') @@ -95956,12 +95956,12 @@ function wp_get_upload_dir() * @type string|false $error False or error message. * } * @phpstan-return array{ - * path?: string, - * url?: string, - * subdir?: string, - * basedir?: string, - * baseurl?: string, - * error?: string|false, + * path: string, + * url: string, + * subdir: string, + * basedir: string, + * baseurl: string, + * error: string|false, * } */ function wp_upload_dir($time = \null, $create_dir = \true, $refresh_cache = \false) @@ -96057,10 +96057,10 @@ function _wp_check_existing_file_names($filename, $files) * @type string|false $error Error message, if there has been an error. * } * @phpstan-return array{ - * file?: string, - * url?: string, - * type?: string, - * error?: string|false, + * file: string, + * url: string, + * type: string, + * error: string|false, * } */ function wp_upload_bits($name, $deprecated, $bits, $time = \null) @@ -96106,8 +96106,8 @@ function wp_get_default_extension_for_mime_type($mime_type) * @type string|false $type File mime type, or false if the file doesn't match a mime type. * } * @phpstan-return array{ - * ext?: string|false, - * type?: string|false, + * ext: string|false, + * type: string|false, * } */ function wp_check_filetype($filename, $mimes = \null) @@ -96137,9 +96137,9 @@ function wp_check_filetype($filename, $mimes = \null) * @type string|false $proper_filename File name with its correct extension, or false if it cannot be determined. * } * @phpstan-return array{ - * ext?: string|false, - * type?: string|false, - * proper_filename?: string|false, + * ext: string|false, + * type: string|false, + * proper_filename: string|false, * } */ function wp_check_filetype_and_ext($file, $filename, $mimes = \null) @@ -96394,9 +96394,9 @@ function _scalar_wp_die_handler($message = '', $title = '', $args = array()) * @type array $2 Arguments to control behavior. * } * @phpstan-return array{ - * 0?: string, - * 1?: string, - * 2?: array, + * 0: string, + * 1: string, + * 2: array, * } */ function _wp_die_process_input($message, $title = '', $args = array()) @@ -100309,11 +100309,11 @@ function wp_safe_remote_head($url, $args = array()) * @type WP_HTTP_Requests_Response|null $http_response Raw HTTP response object. * } * @phpstan-return \WP_Error|array{ - * headers?: string[], - * body?: string, - * response?: array, - * cookies?: WP_HTTP_Cookie[], - * http_response?: WP_HTTP_Requests_Response|null, + * headers: string[], + * body: string, + * response: array, + * cookies: WP_HTTP_Cookie[], + * http_response: WP_HTTP_Requests_Response|null, * } */ function wp_remote_request($url, $args = array()) @@ -101814,12 +101814,12 @@ function _nx($single, $plural, $number, $context, $domain = 'default') * @type string $domain Text domain. * } * @phpstan-return array{ - * 0?: string, - * 1?: string, - * singular?: string, - * plural?: string, - * context?: null, - * domain?: string, + * 0: string, + * 1: string, + * singular: string, + * plural: string, + * context: null, + * domain: string, * } */ function _n_noop($singular, $plural, $domain = \null) @@ -101860,13 +101860,13 @@ function _n_noop($singular, $plural, $domain = \null) * @type string $domain Text domain. * } * @phpstan-return array{ - * 0?: string, - * 1?: string, - * 2?: string, - * singular?: string, - * plural?: string, - * context?: string, - * domain?: string, + * 0: string, + * 1: string, + * 2: string, + * singular: string, + * plural: string, + * context: string, + * domain: string, * } */ function _nx_noop($singular, $plural, $context, $domain = \null) @@ -104005,8 +104005,8 @@ function is_avatar_comment_type($comment_type) * extra_attr?: string, * } $args * @phpstan-return array{ - * found_avatar?: bool, - * url?: string, + * found_avatar: bool, + * url: string, * } */ function get_avatar_data($id_or_email, $args = \null) @@ -104909,8 +104909,8 @@ function wp_get_additional_image_sizes() * @type int $1 The maximum height in pixels. * } * @phpstan-return array{ - * 0?: int, - * 1?: int, + * 0: int, + * 1: int, * } */ function image_constrain_size_for_editor($width, $height, $size = 'medium', $context = \null) @@ -104961,10 +104961,10 @@ function image_hwstring($width, $height) * @type bool $3 Whether the image is a resized image. * } * @phpstan-return false|array{ - * 0?: string, - * 1?: int, - * 2?: int, - * 3?: bool, + * 0: string, + * 1: int, + * 2: int, + * 3: bool, * } */ function image_downsize($id, $size = 'medium') @@ -105073,8 +105073,8 @@ function get_image_tag($id, $alt, $title, $align, $size = 'medium') * @type int $1 The height in pixels. * } * @phpstan-return array{ - * 0?: int, - * 1?: int, + * 0: int, + * 1: int, * } */ function wp_constrain_dimensions($current_width, $current_height, $max_width = 0, $max_height = 0) @@ -105175,11 +105175,11 @@ function wp_image_matches_ratio($source_width, $source_height, $target_width, $t * @type string $url URL of image. * } * @phpstan-return false|array{ - * file?: string, - * width?: int, - * height?: int, - * path?: string, - * url?: string, + * file: string, + * width: int, + * height: int, + * path: string, + * url: string, * } */ function image_get_intermediate_size($post_id, $size = 'thumbnail') @@ -105225,10 +105225,10 @@ function wp_get_registered_image_subsizes() * @type bool $3 Whether the image is a resized image. * } * @phpstan-return false|array{ - * 0?: string, - * 1?: int, - * 2?: int, - * 3?: bool, + * 0: string, + * 1: int, + * 2: int, + * 3: bool, * } */ function wp_get_attachment_image_src($attachment_id, $size = 'thumbnail', $icon = \false) @@ -105321,8 +105321,8 @@ function _wp_get_attachment_relative_path($file) * @type int $1 Image height. * } * @phpstan-return false|array{ - * 0?: int, - * 1?: int, + * 0: int, + * 1: int, * } */ function _wp_get_image_size_from_meta($size_name, $image_meta) @@ -106016,8 +106016,8 @@ function wp_imagecreatetruecolor($width, $height) * @type int $1 The maximum height in pixels. * } * @phpstan-return array{ - * 0?: int, - * 1?: int, + * 0: int, + * 1: int, * } */ function wp_expand_dimensions($example_width, $example_height, $max_width, $max_height) @@ -106129,40 +106129,40 @@ function wp_plupload_default_settings() * } * * @phpstan-return void|array{ - * alt?: string, - * author?: string, - * authorName?: string, - * caption?: string, - * compat?: array, - * context?: string, - * date?: int, - * dateFormatted?: string, - * description?: string, - * editLink?: string, - * filename?: string, - * filesizeHumanReadable?: string, - * filesizeInBytes?: int, - * height?: int, - * icon?: string, - * id?: int, - * link?: string, - * menuOrder?: int, - * meta?: array, - * mime?: string, - * modified?: int, - * name?: string, - * nonces?: array, - * orientation?: string, - * sizes?: array, - * status?: string, - * subtype?: string, - * title?: string, - * type?: string, - * uploadedTo?: int, - * uploadedToLink?: string, - * uploadedToTitle?: string, - * url?: string, - * width?: int, + * alt: string, + * author: string, + * authorName: string, + * caption: string, + * compat: array, + * context: string, + * date: int, + * dateFormatted: string, + * description: string, + * editLink: string, + * filename: string, + * filesizeHumanReadable: string, + * filesizeInBytes: int, + * height: int, + * icon: string, + * id: int, + * link: string, + * menuOrder: int, + * meta: array, + * mime: string, + * modified: int, + * name: string, + * nonces: array, + * orientation: string, + * sizes: array, + * status: string, + * subtype: string, + * title: string, + * type: string, + * uploadedTo: int, + * uploadedToLink: string, + * uploadedToTitle: string, + * url: string, + * width: int, * } */ function wp_prepare_attachment_for_js($attachment) @@ -106373,9 +106373,9 @@ function wp_getimagesize($filename, array &$image_info = \null) * False on failure. * } * @phpstan-return array{ - * width?: int|false, - * height?: int|false, - * type?: string|false, + * width: int|false, + * height: int|false, + * type: string|false, * } */ function wp_get_webp_info($filename) @@ -107222,12 +107222,12 @@ function _update_posts_count_on_transition_post_status($new_status, $old_status, * @type int $deleted The number of deleted sites. * } * @phpstan-return array{ - * all?: int, - * public?: int, - * archived?: int, - * mature?: int, - * spam?: int, - * deleted?: int, + * all: int, + * public: int, + * archived: int, + * mature: int, + * spam: int, + * deleted: int, * } */ function wp_count_sites($network_id = \null) @@ -107661,8 +107661,8 @@ function update_user_status($id, $pref, $value, $deprecated = \null) * @type int $users Number of users on the network. * } * @phpstan-return array{ - * blogs?: int, - * users?: int, + * blogs: int, + * users: int, * } */ function get_sitestats() @@ -107844,10 +107844,10 @@ function is_email_address_unsafe($user_email) * @type WP_Error $errors WP_Error object containing any errors found. * } * @phpstan-return array{ - * user_name?: string, - * orig_username?: string, - * user_email?: string, - * errors?: WP_Error, + * user_name: string, + * orig_username: string, + * user_email: string, + * errors: WP_Error, * } */ function wpmu_validate_user_signup($user_name, $user_email) @@ -107886,12 +107886,12 @@ function wpmu_validate_user_signup($user_name, $user_email) * @type WP_Error $errors WP_Error containing any errors found. * } * @phpstan-return array{ - * domain?: string, - * path?: string, - * blogname?: string, - * blog_title?: string, - * user?: string|WP_User, - * errors?: WP_Error, + * domain: string, + * path: string, + * blogname: string, + * blog_title: string, + * user: string|WP_User, + * errors: WP_Error, * } */ function wpmu_validate_blog_signup($blogname, $blog_title, $user = '') @@ -108277,7 +108277,7 @@ function global_terms($term_id, $deprecated = '') * @type string $0 The current site's domain. * } * @phpstan-return array{ - * 0?: string, + * 0: string, * } */ function redirect_this_site($deprecated = '') @@ -112977,9 +112977,9 @@ function get_children($args = '', $output = \OBJECT) * @type string $more_text Custom read more text, or empty string. * } * @phpstan-return array{ - * main?: string, - * extended?: string, - * more_text?: string, + * main: string, + * extended: string, + * more_text: string, * } */ function get_extended($post) @@ -115048,11 +115048,11 @@ function wp_delete_attachment_files($post_id, $meta, $backup_sizes, $file) * @type array $image_meta Image metadata. * } * @phpstan-return false|array{ - * width?: int, - * height?: int, - * file?: string, - * sizes?: array, - * image_meta?: array, + * width: int, + * height: int, + * file: string, + * sizes: array, + * image_meta: array, * } */ function wp_get_attachment_metadata($attachment_id = 0, $unfiltered = \false) @@ -119910,8 +119910,8 @@ function wp_get_object_terms($object_ids, $taxonomies, $args = array()) * slug?: string, * } $args * @phpstan-return \WP_Error|array{ - * term_id?: int, - * term_taxonomy_id?: int|string, + * term_id: int, + * term_taxonomy_id: int|string, * } */ function wp_insert_term($term, $taxonomy, $args = array()) @@ -122865,8 +122865,8 @@ function update_user_meta($user_id, $meta_key, $meta_value, $prev_value = '') * @type int[] $avail_roles Array of user counts keyed by user role. * } * @phpstan-return array{ - * total_users?: int, - * avail_roles?: int[], + * total_users: int, + * avail_roles: int[], * } */ function count_users($strategy = 'time', $site_id = \null) From 57a18b1d503a241f3b7696951b5b3fe45df691cb Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 Dec 2021 23:47:34 +0100 Subject: [PATCH 29/35] PHP 7.3 syntax. --- visitor.php | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index c41a73f..7e44bfa 100644 --- a/visitor.php +++ b/visitor.php @@ -14,7 +14,10 @@ return new class extends NodeVisitor { - private \phpDocumentor\Reflection\DocBlockFactory $docBlockFactory; + /** + * @var \phpDocumentor\Reflection\DocBlockFactory + */ + private $docBlockFactory; public function __construct() { From 99f196b6e3ba0dd568d48c433309e929205ce7e9 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 3 Dec 2021 00:23:10 +0100 Subject: [PATCH 30/35] Remove temporary PHPStan for testing. --- composer.json | 1 - phpstan.neon | 17 ----------------- 2 files changed, 18 deletions(-) delete mode 100644 phpstan.neon diff --git a/composer.json b/composer.json index 0085701..5938369 100644 --- a/composer.json +++ b/composer.json @@ -14,7 +14,6 @@ "require-dev": { "php": "~7.3 || ~8.0", "phpdocumentor/reflection-docblock": "^5.3", - "phpstan/phpstan": "^1.2", "php-stubs/generator": "^0.8.0", "nikic/php-parser": "< 4.12.0" }, diff --git a/phpstan.neon b/phpstan.neon deleted file mode 100644 index 075aea3..0000000 --- a/phpstan.neon +++ /dev/null @@ -1,17 +0,0 @@ -parameters: - level: 2 - paths: - - wordpress-stubs.php - ignoreErrors: - - '#return statement is missing#' - - '#PHPMailer#' - - '#duplicate keys with value#' - - '#WP_HTTP_Streams#' - - '#unused parameter#' - - '#Constant [A-Z0-9_]+ not found#' - - '#Default value of the parameter#' - - '#\\stream#' - - '#\\GdImage#' - - '#\\IRI#' - - '#Requests#' - - '#SimplePie#' From 294da8d91628e65d9c10719995fc5b508c7483c7 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 3 Dec 2021 00:29:33 +0100 Subject: [PATCH 31/35] More guard conditions. --- visitor.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/visitor.php b/visitor.php index 7e44bfa..cd79622 100644 --- a/visitor.php +++ b/visitor.php @@ -104,8 +104,8 @@ private function getAdditionFromParam(Param $tag): ?string $tagVariableName = $tag->getVariableName(); $tagVariableType = $tag->getType(); - // Skip if the parameter variable name or type are missing. - if (!$tagVariableName || !$tagVariableType) { + // Skip if information we need is missing. + if (!$tagDescription || !$tagVariableName || !$tagVariableType) { return null; } @@ -138,8 +138,8 @@ private function getAdditionFromReturn(Return_ $tag): ?string $tagDescription = $tag->getDescription(); $tagVariableType = $tag->getType(); - // Skip if the return type is missing. - if (!$tagVariableType) { + // Skip if information we need is missing. + if (!$tagDescription || !$tagVariableType) { return null; } From f6c7d9de8ac3851b3fdddd78e03e96e139d4b073 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 3 Dec 2021 00:37:01 +0100 Subject: [PATCH 32/35] Add PHPStan for our lovely new code. --- .travis.yml | 2 ++ composer.json | 1 + phpstan.neon | 4 ++++ 3 files changed, 7 insertions(+) create mode 100644 phpstan.neon diff --git a/.travis.yml b/.travis.yml index 8136830..83d2cc4 100644 --- a/.travis.yml +++ b/.travis.yml @@ -48,3 +48,5 @@ script: - "git diff --exit-code" # Execute stubs - "php -f wordpress-stubs.php" + # Analyse our code + - "vendor/bin/phpstan" diff --git a/composer.json b/composer.json index 5938369..70ae0e5 100644 --- a/composer.json +++ b/composer.json @@ -15,6 +15,7 @@ "php": "~7.3 || ~8.0", "phpdocumentor/reflection-docblock": "^5.3", "php-stubs/generator": "^0.8.0", + "phpstan/phpstan": "^1.2", "nikic/php-parser": "< 4.12.0" }, "suggest": { diff --git a/phpstan.neon b/phpstan.neon new file mode 100644 index 0000000..cb6faa4 --- /dev/null +++ b/phpstan.neon @@ -0,0 +1,4 @@ +parameters: + level: 8 + paths: + - visitor.php From f92b0022a41847d9707ec93c2c988805c14e9baf Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 3 Dec 2021 00:37:28 +0100 Subject: [PATCH 33/35] Fix everything. --- visitor.php | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/visitor.php b/visitor.php index cd79622..2606b2a 100644 --- a/visitor.php +++ b/visitor.php @@ -29,13 +29,13 @@ public function enterNode(Node $node) parent::enterNode($node); if (!($node instanceof Function_) && !($node instanceof ClassMethod)) { - return; + return null; } $docComment = $node->getDocComment(); if (!($docComment instanceof Doc)) { - return; + return null; } $newDocComment = $this->addArrayHashNotation($docComment); @@ -43,6 +43,8 @@ public function enterNode(Node $node) if ($newDocComment !== null) { $node->setDocComment($newDocComment); } + + return null; } private function addArrayHashNotation(Doc $docComment): ?Doc @@ -168,6 +170,10 @@ private function getTypeNameFromType(Type $tagVariableType): ?string // typed arrays such as `int[]` with `array`. $tagVariableType = preg_replace('#[a-zA-Z0-9_]+\[\]#', 'array', $tagVariableType->__toString()); + if ($tagVariableType === null) { + return null; + } + if (strpos($tagVariableType, 'array') === false) { // Skip if we have hash notation that's not for an array (ie. for `object`). return null; @@ -196,11 +202,22 @@ private function getElementsFromDescription(Description $tagDescription, bool $o // Populate `$types` with the value of each top level `@type`. $types = preg_split('/\R+ @type /', $text); + + if (!$types) { + return null; + } + unset($types[0]); $elements = []; foreach ($types as $typeTag) { - list($type, $name) = preg_split('#\s+#', trim($typeTag)); + $parts = preg_split('#\s+#', trim($typeTag)); + + if (!$parts || count($parts) < 2) { + return null; + } + + list($type, $name) = $parts; // Bail out completely if any element doesn't have a static key. if (strpos($name, '...$') !== false) { From 30036735d07ad80d2e4a4bc733f2692787de50d6 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 3 Dec 2021 11:18:49 +0100 Subject: [PATCH 34/35] Update visitor.php MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Viktor Szépe --- visitor.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index 2606b2a..f9310e0 100644 --- a/visitor.php +++ b/visitor.php @@ -203,7 +203,7 @@ private function getElementsFromDescription(Description $tagDescription, bool $o // Populate `$types` with the value of each top level `@type`. $types = preg_split('/\R+ @type /', $text); - if (!$types) { + if ($types === false) { return null; } From 547148f3f65703c76665869f1762029d5c8f5e27 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 3 Dec 2021 11:19:02 +0100 Subject: [PATCH 35/35] Update visitor.php MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Viktor Szépe --- visitor.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/visitor.php b/visitor.php index f9310e0..54456c9 100644 --- a/visitor.php +++ b/visitor.php @@ -213,7 +213,7 @@ private function getElementsFromDescription(Description $tagDescription, bool $o foreach ($types as $typeTag) { $parts = preg_split('#\s+#', trim($typeTag)); - if (!$parts || count($parts) < 2) { + if ($parts === false || count($parts) < 2) { return null; }