Skip to content

Commit d87bf8e

Browse files
szepeviktorszepeviktor
authored
Merge pull request #28 from johnbillion/additional-parameters
2 parents a52949d + 24ced7d commit d87bf8e

File tree

4 files changed

+128
-1
lines changed

4 files changed

+128
-1
lines changed

‎composer.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
"require-dev": {
1212
"php": "~7.3 || ~8.0",
1313
"nikic/php-parser": "< 4.12.0",
14-
"php-stubs/generator": "^0.8.0",
14+
"php-stubs/generator": "dev-master",
1515
"phpdocumentor/reflection-docblock": "^5.3",
1616
"phpstan/phpstan": "^1.2"
1717
},

‎functionMap.php

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?php
2+
3+
$httpReturnType = 'array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error';
4+
5+
/**
6+
* This array is in the same format as the function map array in PHPStan:
7+
*
8+
* '<function_name>' => ['<return_type>, '<arg_name>'=>'<arg_type>']
9+
*
10+
* @link https://github.com/phpstan/phpstan-src/blob/1.5.x/resources/functionMap.php
11+
*/
12+
return [
13+
'add_meta_box' => ['void', 'context'=>'"normal"|"side"|"advanced"', 'priority'=>'"high"|"core"|"default"|"low"'],
14+
'remove_meta_box' => ['void', 'context'=>'"normal"|"side"|"advanced"'],
15+
'WP_Http::get' => [$httpReturnType],
16+
'WP_Http::head' => [$httpReturnType],
17+
'WP_Http::post' => [$httpReturnType],
18+
'WP_Http::request' => [$httpReturnType],
19+
'WP_List_Table::bulk_actions' => ['void', 'which'=>'"top"|"bottom"'],
20+
'WP_List_Table::display_tablenav' => ['void', 'which'=>'"top"|"bottom"'],
21+
'WP_List_Table::pagination' => ['void', 'which'=>'"top"|"bottom"'],
22+
'wp_remote_get' => [$httpReturnType],
23+
'wp_remote_head' => [$httpReturnType],
24+
'wp_remote_post' => [$httpReturnType],
25+
'wp_remote_request' => [$httpReturnType],
26+
'wp_safe_remote_get' => [$httpReturnType],
27+
'wp_safe_remote_head' => [$httpReturnType],
28+
'wp_safe_remote_post' => [$httpReturnType],
29+
'wp_safe_remote_request' => [$httpReturnType],
30+
];

‎visitor.php

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,16 @@
1919
*/
2020
private $docBlockFactory;
2121

22+
/**
23+
* @var ?array<string,array<int|string,string>>
24+
*/
25+
private $functionMap = null;
26+
27+
/**
28+
* @var string
29+
*/
30+
private $currentSymbolName;
31+
2232
public function __construct()
2333
{
2434
$this->docBlockFactory = \phpDocumentor\Reflection\DocBlockFactory::createInstance();
@@ -38,12 +48,39 @@ public function enterNode(Node $node)
3848
return null;
3949
}
4050

51+
$this->currentSymbolName = $node->name->name;
52+
53+
if ($node instanceof ClassMethod) {
54+
/** @var \PhpParser\Node\Stmt\Class_ $parent */
55+
$parent = $this->stack[count($this->stack) - 2];
56+
57+
if (isset($parent->name)) {
58+
$this->currentSymbolName = sprintf(
59+
'%1$s::%2$s',
60+
$parent->name->name,
61+
$node->name->name
62+
);
63+
}
64+
}
65+
4166
$newDocComment = $this->addArrayHashNotation($docComment);
4267

4368
if ($newDocComment !== null) {
4469
$node->setDocComment($newDocComment);
4570
}
4671

72+
$docComment = $node->getDocComment();
73+
74+
if (!($docComment instanceof Doc)) {
75+
return null;
76+
}
77+
78+
$newDocComment = $this->addAdditionalParams($docComment);
79+
80+
if ($newDocComment !== null) {
81+
$node->setDocComment($newDocComment);
82+
}
83+
4784
return null;
4885
}
4986

@@ -100,6 +137,43 @@ private function addArrayHashNotation(Doc $docComment): ?Doc
100137
return new Doc($newDocComment, $docComment->getLine(), $docComment->getFilePos());
101138
}
102139

140+
private function addAdditionalParams(Doc $docComment): ?Doc
141+
{
142+
if (! isset($this->functionMap)) {
143+
$this->functionMap = require __DIR__ . '/functionMap.php';
144+
}
145+
146+
if (! isset($this->functionMap[$this->currentSymbolName])) {
147+
return null;
148+
}
149+
150+
$parameters = $this->functionMap[$this->currentSymbolName];
151+
$returnType = array_shift($parameters);
152+
$additions = [];
153+
154+
foreach ($parameters as $paramName => $paramType) {
155+
$additions[] = sprintf(
156+
'@phpstan-param %s $%s',
157+
$paramType,
158+
$paramName
159+
);
160+
}
161+
162+
$additions[] = sprintf(
163+
'@phpstan-return %s',
164+
$returnType
165+
);
166+
167+
$docCommentText = $docComment->getText();
168+
$newDocComment = sprintf(
169+
"%s\n * %s\n */",
170+
substr($docCommentText, 0, -4),
171+
implode("\n * ", $additions)
172+
);
173+
174+
return new Doc($newDocComment, $docComment->getLine(), $docComment->getFilePos());
175+
}
176+
103177
private function getAdditionFromParam(Param $tag): ?string
104178
{
105179
$tagDescription = $tag->getDescription();

‎wordpress-stubs.php

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4290,6 +4290,8 @@ protected function get_bulk_actions()
42904290
*
42914291
* @param string $which The location of the bulk actions: 'top' or 'bottom'.
42924292
* This is designated as optional for backward compatibility.
4293+
* @phpstan-param "top"|"bottom" $which
4294+
* @phpstan-return void
42934295
*/
42944296
protected function bulk_actions($which = '')
42954297
{
@@ -4378,6 +4380,8 @@ protected function get_items_per_page($option, $default = 20)
43784380
* @since 3.1.0
43794381
*
43804382
* @param string $which
4383+
* @phpstan-param "top"|"bottom" $which
4384+
* @phpstan-return void
43814385
*/
43824386
protected function pagination($which)
43834387
{
@@ -4494,6 +4498,8 @@ protected function get_table_classes()
44944498
*
44954499
* @since 3.1.0
44964500
* @param string $which
4501+
* @phpstan-param "top"|"bottom" $which
4502+
* @phpstan-return void
44974503
*/
44984504
protected function display_tablenav($which)
44994505
{
@@ -40697,6 +40703,7 @@ class WP_Http
4069740703
* filename?: string,
4069840704
* limit_response_size?: int,
4069940705
* } $args
40706+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
4070040707
*/
4070140708
public function request($url, $args = array())
4070240709
{
@@ -40785,6 +40792,7 @@ private function _dispatch_request($url, $args)
4078540792
* @param string|array $args Optional. Override the defaults.
4078640793
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
4078740794
* A WP_Error instance upon error.
40795+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
4078840796
*/
4078940797
public function post($url, $args = array())
4079040798
{
@@ -40800,6 +40808,7 @@ public function post($url, $args = array())
4080040808
* @param string|array $args Optional. Override the defaults.
4080140809
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
4080240810
* A WP_Error instance upon error.
40811+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
4080340812
*/
4080440813
public function get($url, $args = array())
4080540814
{
@@ -40815,6 +40824,7 @@ public function get($url, $args = array())
4081540824
* @param string|array $args Optional. Override the defaults.
4081640825
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
4081740826
* A WP_Error instance upon error.
40827+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
4081840828
*/
4081940829
public function head($url, $args = array())
4082040830
{
@@ -81891,6 +81901,9 @@ function wp_import_upload_form($action)
8189181901
* @param array $callback_args Optional. Data that should be set as the $args property
8189281902
* of the box array (which is the second parameter passed
8189381903
* to your callback). Default null.
81904+
* @phpstan-param "normal"|"side"|"advanced" $context
81905+
* @phpstan-param "high"|"core"|"default"|"low" $priority
81906+
* @phpstan-return void
8189481907
*/
8189581908
function add_meta_box($id, $title, $callback, $screen = \null, $context = 'advanced', $priority = 'default', $callback_args = \null)
8189681909
{
@@ -81970,6 +81983,8 @@ function do_meta_boxes($screen, $context, $object)
8197081983
* include 'normal', 'side', and 'advanced'. Comments screen contexts
8197181984
* include 'normal' and 'side'. Menus meta boxes (accordion sections)
8197281985
* all use the 'side' context.
81986+
* @phpstan-param "normal"|"side"|"advanced" $context
81987+
* @phpstan-return void
8197381988
*/
8197481989
function remove_meta_box($id, $screen, $context)
8197581990
{
@@ -104003,6 +104018,7 @@ function _wp_http_get_object()
104003104018
* @param string $url URL to retrieve.
104004104019
* @param array $args Optional. Request arguments. Default empty array.
104005104020
* @return array|WP_Error The response or WP_Error on failure.
104021+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
104006104022
*/
104007104023
function wp_safe_remote_request($url, $args = array())
104008104024
{
@@ -104021,6 +104037,7 @@ function wp_safe_remote_request($url, $args = array())
104021104037
* @param string $url URL to retrieve.
104022104038
* @param array $args Optional. Request arguments. Default empty array.
104023104039
* @return array|WP_Error The response or WP_Error on failure.
104040+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
104024104041
*/
104025104042
function wp_safe_remote_get($url, $args = array())
104026104043
{
@@ -104039,6 +104056,7 @@ function wp_safe_remote_get($url, $args = array())
104039104056
* @param string $url URL to retrieve.
104040104057
* @param array $args Optional. Request arguments. Default empty array.
104041104058
* @return array|WP_Error The response or WP_Error on failure.
104059+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
104042104060
*/
104043104061
function wp_safe_remote_post($url, $args = array())
104044104062
{
@@ -104057,6 +104075,7 @@ function wp_safe_remote_post($url, $args = array())
104057104075
* @param string $url URL to retrieve.
104058104076
* @param array $args Optional. Request arguments. Default empty array.
104059104077
* @return array|WP_Error The response or WP_Error on failure.
104078+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
104060104079
*/
104061104080
function wp_safe_remote_head($url, $args = array())
104062104081
{
@@ -104097,6 +104116,7 @@ function wp_safe_remote_head($url, $args = array())
104097104116
* cookies: WP_HTTP_Cookie[],
104098104117
* http_response: WP_HTTP_Requests_Response|null,
104099104118
* }
104119+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
104100104120
*/
104101104121
function wp_remote_request($url, $args = array())
104102104122
{
@@ -104112,6 +104132,7 @@ function wp_remote_request($url, $args = array())
104112104132
* @param string $url URL to retrieve.
104113104133
* @param array $args Optional. Request arguments. Default empty array.
104114104134
* @return array|WP_Error The response or WP_Error on failure.
104135+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
104115104136
*/
104116104137
function wp_remote_get($url, $args = array())
104117104138
{
@@ -104127,6 +104148,7 @@ function wp_remote_get($url, $args = array())
104127104148
* @param string $url URL to retrieve.
104128104149
* @param array $args Optional. Request arguments. Default empty array.
104129104150
* @return array|WP_Error The response or WP_Error on failure.
104151+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
104130104152
*/
104131104153
function wp_remote_post($url, $args = array())
104132104154
{
@@ -104142,6 +104164,7 @@ function wp_remote_post($url, $args = array())
104142104164
* @param string $url URL to retrieve.
104143104165
* @param array $args Optional. Request arguments. Default empty array.
104144104166
* @return array|WP_Error The response or WP_Error on failure.
104167+
* @phpstan-return array{headers: \Requests_Utility_CaseInsensitiveDictionary, body: string, response: array{code: int,message: string}, cookies: array<int, \WP_HTTP_Cookie>, filename: string|null, http_response: \WP_HTTP_Requests_Response}|\WP_Error
104145104168
*/
104146104169
function wp_remote_head($url, $args = array())
104147104170
{

0 commit comments

Comments
 (0)