Skip to content

Commit 88f65d1

Browse files
claudeswissspidy
andcommitted
Docs: Bring the types from php-stubs/wordpress-stubs' function map into core.
php-stubs/wordpress-stubs, from which every plugin's static analysis takes its view of core, applies a map of PHPStan types on top of core's docblocks when it generates the stubs: conditional return types, narrowed parameters, templates, purity and a few class-level annotations. szepeviktor/phpstan-wordpress dropped its own return type extensions in favor of that map. Each entry is a type core could carry itself, and one carried here reaches core's own analysis, the stubs, and every plugin from one place. This adds the map's entries to the docblocks of the 290 functions, methods, properties and classes it names, as `@phpstan-` tags. An entry is left out where core already carries a `@phpstan-return` or template for the symbol, where the parameter or return is documented with hash notation that `HashNotationVisitor` derives a shape from, or where the symbol lives in Gutenberg. A few entries were wrong for core and are adjusted or dropped: `add_shortcode()` callbacks receive a string rather than an array when a shortcode has no attributes, `_get_list_table()` accepts a `WP_Screen` as well as a name, `get_tag_regex()` and `wp_get_inline_script_tag()` do return an empty string, `wp_update_comment()` returns the row count `wpdb::update()` does, `size_format()` and `get_tags()` are stated in terms of what core's parameter and `get_terms()` types allow, `get_html_split_regex()`, `block_version()` and `wp_is_uuid()` are not pure, and the `WP_REST_Request` generics report every offset assignment in core as an error and are not adopted. Five calls the new types show to be passing something other than the documented value are corrected: `wp_upload_bits()` and `add_option()` are given the value their deprecated parameter documents, `iframe_header()` is no longer given a deprecated argument, `switch_to_blog()` is given the site ID as an int, and `get_term_to_edit()` documents the `WP_Term` it returns. The baselines lose 53 entries the new types resolve, including every `parameter.defaultValue` and `method.nonObject` error, and gain 8: seven reworded, and one `WP_Term_Query::populate_terms()` assignment on what `get_term()` may return that is worth a look of its own. Co-authored-by: Pascal Birchler <pascal.birchler@gmail.com> Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013QJ9RphuttTR7cS5G4mU21
1 parent c60fe94 commit 88f65d1

89 files changed

Lines changed: 921 additions & 284 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/wp-admin/includes/bookmark.php‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
* @since 2.0.0
1313
*
1414
* @return int The link ID on success. The value 0 on failure.
15+
*
16+
* @phpstan-return int<0, max>
1517
*/
1618
function add_link() {
1719
return edit_link();
@@ -24,6 +26,8 @@ function add_link() {
2426
*
2527
* @param int $link_id Optional. ID of the link to edit. Default 0.
2628
* @return int The link ID on success. The value 0 on failure.
29+
*
30+
* @phpstan-return int<0, max>
2731
*/
2832
function edit_link( $link_id = 0 ) {
2933
if ( ! current_user_can( 'manage_links' ) ) {
@@ -56,6 +60,9 @@ function edit_link( $link_id = 0 ) {
5660
* @since 2.0.0
5761
*
5862
* @return stdClass Default link object.
63+
*
64+
* @phpstan-impure
65+
* @phpstan-return object{link_url: string, link_name: string, link_visible: 'Y'}&stdClass
5966
*/
6067
function get_default_link_to_edit() {
6168
$link = new stdClass();
@@ -122,6 +129,8 @@ function wp_delete_link( $link_id ) {
122129
*
123130
* @param int $link_id Link ID to look up.
124131
* @return int[] The IDs of the requested link's categories.
132+
*
133+
* @phpstan-return ($link_id is empty ? array{} : array<int, int<1, max>>)
125134
*/
126135
function wp_get_link_cats( $link_id = 0 ) {
127136
$cats = wp_get_object_terms( $link_id, 'link_category', array( 'fields' => 'ids' ) );
@@ -170,6 +179,8 @@ function get_link_to_edit( $link ) {
170179
* }
171180
* @param bool $wp_error Optional. Whether to return a WP_Error object on failure. Default false.
172181
* @return int|WP_Error The link ID on success. The value 0 or WP_Error on failure.
182+
*
183+
* @phpstan-return ($wp_error is false ? int<0, max> : int<0, max>|WP_Error)
173184
*/
174185
function wp_insert_link( $linkdata, $wp_error = false ) {
175186
global $wpdb;
@@ -296,6 +307,8 @@ function wp_set_link_cats( $link_id = 0, $link_categories = array() ) {
296307
*
297308
* @param array $linkdata Link data to update. See wp_insert_link() for accepted arguments.
298309
* @return int The updated link ID on success. The value 0 on failure.
310+
*
311+
* @phpstan-return int<0, max>
299312
*/
300313
function wp_update_link( $linkdata ) {
301314
$link_id = (int) $linkdata['link_id'];

‎src/wp-admin/includes/class-custom-background.php‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ class Custom_Background {
1919
*
2020
* @since 3.0.0
2121
* @var callable
22+
*
23+
* @phpstan-var ''|callable(): void
2224
*/
2325
public $admin_header_callback;
2426

@@ -27,6 +29,8 @@ class Custom_Background {
2729
*
2830
* @since 3.0.0
2931
* @var callable
32+
*
33+
* @phpstan-var ''|callable(): void
3034
*/
3135
public $admin_image_div_callback;
3236

@@ -47,6 +51,9 @@ class Custom_Background {
4751
* Default empty string.
4852
* @param callable $admin_image_div_callback Optional. Custom image div output callback.
4953
* Default empty string.
54+
*
55+
* @phpstan-param ''|callable(): void $admin_header_callback
56+
* @phpstan-param ''|callable(): void $admin_image_div_callback
5057
*/
5158
public function __construct( $admin_header_callback = '', $admin_image_div_callback = '' ) {
5259
$this->admin_header_callback = $admin_header_callback;

‎src/wp-admin/includes/class-custom-image-header.php‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ class Custom_Image_Header {
1919
*
2020
* @since 2.1.0
2121
* @var callable
22+
*
23+
* @phpstan-var ''|callable(): void
2224
*/
2325
public $admin_header_callback;
2426

@@ -27,6 +29,8 @@ class Custom_Image_Header {
2729
*
2830
* @since 3.0.0
2931
* @var callable
32+
*
33+
* @phpstan-var ''|callable(): void
3034
*/
3135
public $admin_image_div_callback;
3236

@@ -54,6 +58,8 @@ class Custom_Image_Header {
5458
* @param callable $admin_header_callback Administration header callback.
5559
* @param callable $admin_image_div_callback Optional. Custom image div output callback.
5660
* Default empty string.
61+
*
62+
* @phpstan-param ''|callable(): void $admin_image_div_callback
5763
*/
5864
public function __construct( $admin_header_callback, $admin_image_div_callback = '' ) {
5965
$this->admin_header_callback = $admin_header_callback;
@@ -310,6 +316,8 @@ public function process_default_headers() {
310316
*
311317
* @param string $type The header type. One of 'default' (for the Uploaded Images control)
312318
* or 'uploaded' (for the Uploaded Images control).
319+
*
320+
* @phpstan-param 'default'|'uploaded' $type
313321
*/
314322
public function show_header_selector( $type = 'default' ) {
315323
if ( 'default' === $type ) {
@@ -1169,6 +1177,13 @@ public function filter_upload_tabs( $tabs ) {
11691177
* registered for that theme; and the key of an image uploaded for that theme
11701178
* (the attachment ID of the image). Or an array of arguments: attachment_id,
11711179
* url, width, height. All are required.
1180+
*
1181+
* @phpstan-param string|array{
1182+
* attachment_id: int<1, max>,
1183+
* url: string,
1184+
* width: int<0, max>,
1185+
* height: int<0, max>,
1186+
* } $choice
11721187
*/
11731188
final public function set_header_image( $choice ) {
11741189
if ( is_array( $choice ) || is_object( $choice ) ) {

‎src/wp-admin/includes/class-wp-comments-list-table.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ public function __construct( $args = array() ) {
6262
* @param string $name Comment author name.
6363
* @param int $comment_id Comment ID.
6464
* @return string Avatar with the user name.
65+
*
66+
* @phpstan-return non-falsy-string
6567
*/
6668
public function floated_admin_avatar( $name, $comment_id ) {
6769
$comment = get_comment( $comment_id );

‎src/wp-admin/includes/class-wp-list-table.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,9 @@ public function prepare_items() {
319319
* @since 3.1.0
320320
*
321321
* @param array|string $args Array or string of arguments with information about the pagination.
322+
*
323+
* @phpstan-param array{total_items?: int, total_pages?: int, per_page?: int} $args
324+
* @phpstan-return void
322325
*/
323326
protected function set_pagination_args( $args ) {
324327
$args = wp_parse_args(

‎src/wp-admin/includes/image.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -635,7 +635,7 @@ function wp_generate_attachment_metadata( $attachment_id, $file ) {
635635
break;
636636
}
637637
$basename = str_replace( '.', '-', wp_basename( $file ) ) . '-image' . $ext;
638-
$uploaded = wp_upload_bits( $basename, '', $metadata['image']['data'] );
638+
$uploaded = wp_upload_bits( $basename, null, $metadata['image']['data'] );
639639
if ( false === $uploaded['error'] ) {
640640
$image_attachment = array(
641641
'post_mime_type' => $metadata['image']['mime'],

‎src/wp-admin/includes/list-table.php‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,15 @@
1717
* @param string $class_name The type of the list table, which is the class name.
1818
* @param array $args Optional. Arguments to pass to the class. Accepts 'screen'.
1919
* @return WP_List_Table|false List table object on success, false if the class does not exist.
20+
*
21+
* @phpstan-template T of string
22+
* @phpstan-param T $class_name
23+
* @phpstan-param array{screen?: string|WP_Screen|null} $args
24+
* @phpstan-return (
25+
* $class_name is 'WP_Posts_List_Table'|'WP_Media_List_Table'|'WP_Terms_List_Table'|'WP_Users_List_Table'|'WP_Comments_List_Table'|'WP_Post_Comments_List_Table'|'WP_Links_List_Table'|'WP_Plugin_Install_List_Table'|'WP_Themes_List_Table'|'WP_Theme_Install_List_Table'|'WP_Plugins_List_Table'|'WP_Application_Passwords_List_Table'|'WP_MS_Sites_List_Table'|'WP_MS_Users_List_Table'|'WP_MS_Themes_List_Table'|'WP_Privacy_Data_Export_Requests_List_Table'|'WP_Privacy_Data_Removal_Requests_List_Table'
26+
* ? new<T>
27+
* : false
28+
* )
2029
*/
2130
function _get_list_table( $class_name, $args = array() ) {
2231
$core_classes = array(

‎src/wp-admin/includes/media.php‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1238,6 +1238,8 @@ function image_align_input_fields( $post, $checked = '' ) {
12381238
* @param WP_Post $post
12391239
* @param bool|string $check
12401240
* @return array<string, string> An array of data for the image size input fields.
1241+
*
1242+
* @phpstan-return array{label: string, input: 'html', html: string}
12411243
*/
12421244
function image_size_input_fields( $post, $check = '' ) {
12431245
/**
@@ -1316,6 +1318,8 @@ function image_size_input_fields( $post, $check = '' ) {
13161318
* @param WP_Post $post
13171319
* @param string $url_type
13181320
* @return string HTML markup for the link URL buttons.
1321+
*
1322+
* @phpstan-return non-falsy-string
13191323
*/
13201324
function image_link_input_fields( $post, $url_type = '' ) {
13211325

@@ -1349,6 +1353,8 @@ function image_link_input_fields( $post, $url_type = '' ) {
13491353
*
13501354
* @param WP_Post $edit_post Attachment WP_Post object.
13511355
* @return string HTML markup for the textarea element.
1356+
*
1357+
* @phpstan-return non-falsy-string
13521358
*/
13531359
function wp_caption_input_textarea( $edit_post ) {
13541360
// Post data is already escaped.
@@ -1638,6 +1644,8 @@ function get_media_items( $post_id, $errors ) {
16381644
* @param int $attachment_id Attachment ID for modification.
16391645
* @param string|array $args Optional. Override defaults.
16401646
* @return string HTML form for attachment.
1647+
*
1648+
* @phpstan-return non-falsy-string
16411649
*/
16421650
function get_media_item( $attachment_id, $args = null ) {
16431651
global $redir_tab;
@@ -1932,6 +1940,8 @@ function get_media_item( $attachment_id, $args = null ) {
19321940
* @param int $attachment_id
19331941
* @param array $args
19341942
* @return array<string, string> An array containing the media item and its metadata.
1943+
*
1944+
* @phpstan-return array{item: string, meta: string}
19351945
*/
19361946
function get_compat_media_markup( $attachment_id, $args = null ) {
19371947
$post = get_post( $attachment_id );
@@ -3014,6 +3024,8 @@ function media_upload_library_form( $errors ) {
30143024
*
30153025
* @param string $default_view
30163026
* @return string HTML content of the form.
3027+
*
3028+
* @phpstan-return non-falsy-string
30173029
*/
30183030
function wp_media_insert_url_form( $default_view = 'image' ) {
30193031
/** This filter is documented in wp-admin/includes/media.php */

‎src/wp-admin/includes/menu.php‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,11 @@
208208
* @param string $class_to_add The CSS class to add.
209209
* @param string $classes The string to add the CSS class to.
210210
* @return string The string with the CSS class added.
211+
*
212+
* @phpstan-template T of string
213+
* @phpstan-param T $class_to_add
214+
* @phpstan-pure
215+
* @phpstan-return ($classes is empty ? T : non-empty-string)
211216
*/
212217
function add_cssclass( $class_to_add, $classes ) {
213218
if ( empty( $classes ) ) {

‎src/wp-admin/includes/meta-boxes.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1257,6 +1257,8 @@ function link_target_meta_box( $link ) {
12571257
* if it matches the current link's relationship.
12581258
* Default empty string.
12591259
* @param mixed $deprecated Deprecated. Not used.
1260+
*
1261+
* @phpstan-param '' $deprecated
12601262
*/
12611263
function xfn_check( $xfn_relationship, $xfn_value = '', $deprecated = '' ) {
12621264
global $link;

0 commit comments

Comments
 (0)