Build/Test Tools: Use szepeviktor/phpstan-wordpress for the extensions core does not need to write itself

composer.json

@@ -53,6 +53,7 @@
 		"phpcompatibility/phpcompatibility-wp": "~2.1.3",
 		"phpstan/phpstan": "2.2.13",
 		"phpstan/phpstan-phpunit": "2.0.18",
+		"szepeviktor/phpstan-wordpress": "^2.0.4",
 		"yoast/phpunit-polyfills": "^1.1.0"
 	},
 	"config": {

phpstan.neon.dist

@@ -54,15 +54,13 @@ includes:
 	- tests/phpstan/baselines/isset.offset.neon
 	- tests/phpstan/baselines/isset.property.neon
 	- tests/phpstan/baselines/method.childParameterType.neon
-	- tests/phpstan/baselines/method.nonObject.neon
 	- tests/phpstan/baselines/method.unused.neon
 	- tests/phpstan/baselines/notIdentical.alwaysTrue.neon
 	- tests/phpstan/baselines/nullCoalesce.offset.neon
 	- tests/phpstan/baselines/nullCoalesce.property.neon
 	- tests/phpstan/baselines/offsetAccess.nonOffsetAccessible.neon
 	- tests/phpstan/baselines/offsetAccess.notFound.neon
 	- tests/phpstan/baselines/offsetAssign.valueType.neon
-	- tests/phpstan/baselines/parameter.defaultValue.neon
 	- tests/phpstan/baselines/parameter.notFound.neon
 	- tests/phpstan/baselines/parameter.phpDocType.neon
 	- tests/phpstan/baselines/parameterByRef.type.neon

src/wp-admin/customize.php

@@ -110,8 +110,10 @@
 $wp_scripts             = new WP_Scripts();
 $wp_scripts->registered = $registered;
 
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'customize_controls_print_scripts', 'print_head_scripts', 20 );
 add_action( 'customize_controls_print_footer_scripts', '_wp_footer_scripts' );
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'customize_controls_print_styles', 'print_admin_styles', 20 );
 
 /**

src/wp-admin/includes/admin-filters.php

@@ -11,16 +11,21 @@
 add_action( 'admin_page_access_denied', 'wp_link_manager_disabled_message' );
 
 // Dashboard hooks.
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'activity_box_end', 'wp_dashboard_quota' );
 add_action( 'welcome_panel', 'wp_welcome_panel' );
 
 // Media hooks.
 add_action( 'attachment_submitbox_misc_actions', 'attachment_submitbox_metadata' );
 add_filter( 'plupload_init', 'wp_show_heic_upload_error' );
 
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'media_upload_image', 'wp_media_upload_handler' );
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'media_upload_audio', 'wp_media_upload_handler' );
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'media_upload_video', 'wp_media_upload_handler' );
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'media_upload_file', 'wp_media_upload_handler' );
 
 add_action( 'post-plupload-upload-ui', 'media_upload_flash_bypass' );
@@ -57,10 +62,12 @@
 }
 
 add_action( 'admin_print_scripts', 'print_emoji_detection_script' );
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'admin_print_scripts', 'print_head_scripts', 20 );
 add_action( 'admin_print_footer_scripts', '_wp_footer_scripts' );
 add_action( 'admin_enqueue_scripts', 'wp_enqueue_emoji_styles' );
 add_action( 'admin_print_styles', 'print_emoji_styles' ); // Retained for backwards-compatibility. Unhooked by wp_enqueue_emoji_styles().
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'admin_print_styles', 'print_admin_styles', 20 );
 
 add_action( 'admin_print_scripts-index.php', 'wp_localize_community_events' );
@@ -130,10 +137,12 @@
 add_action( 'load-plugins.php', 'wp_plugin_update_rows', 20 ); // After wp_update_plugins() is called.
 add_action( 'load-themes.php', 'wp_theme_update_rows', 20 ); // After wp_update_themes() is called.
 
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'admin_notices', 'update_nag', 3 );
 add_action( 'admin_notices', 'deactivated_plugins_notice', 5 );
 add_action( 'admin_notices', 'paused_plugins_notice', 5 );
 add_action( 'admin_notices', 'paused_themes_notice', 5 );
+// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 add_action( 'admin_notices', 'maintenance_nag', 10 );
 add_action( 'admin_notices', 'wp_recovery_mode_nag', 1 );
 

src/wp-admin/includes/bookmark.php

@@ -12,6 +12,8 @@
  * @since 2.0.0
  *
  * @return int The link ID on success. The value 0 on failure.
+ *
+ * @phpstan-return int<0, max>
  */
 function add_link() {
 	return edit_link();
@@ -24,6 +26,8 @@ function add_link() {
  *
  * @param int $link_id Optional. ID of the link to edit. Default 0.
  * @return int The link ID on success. The value 0 on failure.
+ *
+ * @phpstan-return int<0, max>
  */
 function edit_link( $link_id = 0 ) {
 	if ( ! current_user_can( 'manage_links' ) ) {
@@ -56,6 +60,9 @@ function edit_link( $link_id = 0 ) {
  * @since 2.0.0
  *
  * @return stdClass Default link object.
+ *
+ * @phpstan-impure
+ * @phpstan-return object{link_url: string, link_name: string, link_visible: 'Y'}&stdClass
  */
 function get_default_link_to_edit() {
 	$link = new stdClass();
@@ -122,6 +129,8 @@ function wp_delete_link( $link_id ) {
  *
  * @param int $link_id Link ID to look up.
  * @return int[] The IDs of the requested link's categories.
+ *
+ * @phpstan-return ($link_id is empty ? array{} : array<int, int<1, max>>)
  */
 function wp_get_link_cats( $link_id = 0 ) {
 	$cats = wp_get_object_terms( $link_id, 'link_category', array( 'fields' => 'ids' ) );
@@ -170,6 +179,8 @@ 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 The link ID on success. The value 0 or WP_Error on failure.
+ *
+ * @phpstan-return ($wp_error is false ? int<0, max> : int<0, max>|WP_Error)
  */
 function wp_insert_link( $linkdata, $wp_error = false ) {
 	global $wpdb;
@@ -296,6 +307,8 @@ function wp_set_link_cats( $link_id = 0, $link_categories = array() ) {
  *
  * @param array $linkdata Link data to update. See wp_insert_link() for accepted arguments.
  * @return int The updated link ID on success. The value 0 on failure.
+ *
+ * @phpstan-return int<0, max>
  */
 function wp_update_link( $linkdata ) {
 	$link_id = (int) $linkdata['link_id'];

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

@@ -19,6 +19,8 @@ class Custom_Background {
 	 *
 	 * @since 3.0.0
 	 * @var callable
+	 *
+	 * @phpstan-var ''|callable(): void
 	 */
 	public $admin_header_callback;
 
@@ -27,6 +29,8 @@ class Custom_Background {
 	 *
 	 * @since 3.0.0
 	 * @var callable
+	 *
+	 * @phpstan-var ''|callable(): void
 	 */
 	public $admin_image_div_callback;
 
@@ -47,6 +51,9 @@ class Custom_Background {
 	 *                                           Default empty string.
 	 * @param callable $admin_image_div_callback Optional. Custom image div output callback.
 	 *                                           Default empty string.
+	 *
+	 * @phpstan-param ''|callable(): void $admin_header_callback
+	 * @phpstan-param ''|callable(): void $admin_image_div_callback
 	 */
 	public function __construct( $admin_header_callback = '', $admin_image_div_callback = '' ) {
 		$this->admin_header_callback    = $admin_header_callback;

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

@@ -19,6 +19,8 @@ class Custom_Image_Header {
 	 *
 	 * @since 2.1.0
 	 * @var callable
+	 *
+	 * @phpstan-var ''|callable(): void
 	 */
 	public $admin_header_callback;
 
@@ -27,6 +29,8 @@ class Custom_Image_Header {
 	 *
 	 * @since 3.0.0
 	 * @var callable
+	 *
+	 * @phpstan-var ''|callable(): void
 	 */
 	public $admin_image_div_callback;
 
@@ -54,6 +58,8 @@ class Custom_Image_Header {
 	 * @param callable $admin_header_callback    Administration header callback.
 	 * @param callable $admin_image_div_callback Optional. Custom image div output callback.
 	 *                                           Default empty string.
+	 *
+	 * @phpstan-param ''|callable(): void $admin_image_div_callback
 	 */
 	public function __construct( $admin_header_callback, $admin_image_div_callback = '' ) {
 		$this->admin_header_callback    = $admin_header_callback;
@@ -310,6 +316,8 @@ public function process_default_headers() {
 	 *
 	 * @param string $type The header type. One of 'default' (for the Uploaded Images control)
 	 *                     or 'uploaded' (for the Uploaded Images control).
+	 *
+	 * @phpstan-param 'default'|'uploaded' $type
 	 */
 	public function show_header_selector( $type = 'default' ) {
 		if ( 'default' === $type ) {
@@ -1169,6 +1177,13 @@ public function filter_upload_tabs( $tabs ) {
 	 *                      registered for that theme; and the key of an image uploaded for that theme
 	 *                      (the attachment ID of the image). Or an array of arguments: attachment_id,
 	 *                      url, width, height. All are required.
+	 *
+	 * @phpstan-param string|array{
+	 *     attachment_id: int<1, max>,
+	 *     url: string,
+	 *     width: int<0, max>,
+	 *     height: int<0, max>,
+	 * } $choice
 	 */
 	final public function set_header_image( $choice ) {
 		if ( is_array( $choice ) || is_object( $choice ) ) {

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

@@ -62,6 +62,8 @@ public function __construct( $args = array() ) {
 	 * @param string $name       Comment author name.
 	 * @param int    $comment_id Comment ID.
 	 * @return string Avatar with the user name.
+	 *
+	 * @phpstan-return non-falsy-string
 	 */
 	public function floated_admin_avatar( $name, $comment_id ) {
 		$comment = get_comment( $comment_id );

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

@@ -319,6 +319,9 @@ public function prepare_items() {
 	 * @since 3.1.0
 	 *
 	 * @param array|string $args Array or string of arguments with information about the pagination.
+	 *
+	 * @phpstan-param array{total_items?: int, total_pages?: int, per_page?: int} $args
+	 * @phpstan-return void
 	 */
 	protected function set_pagination_args( $args ) {
 		$args = wp_parse_args(

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

@@ -1856,7 +1856,7 @@ public function inline_edit() {
 							 * @param array $users_opt An array of arguments passed to wp_dropdown_users().
 							 * @param bool  $bulk      A flag to denote if it's a bulk action.
 							 */
-							$users_opt = apply_filters( 'quick_edit_dropdown_authors_args', $users_opt, $bulk );
+							$users_opt = apply_filters( 'quick_edit_dropdown_authors_args', $users_opt, (bool) $bulk );
 
 							$authors = wp_dropdown_users( $users_opt );
 
@@ -1961,7 +1961,7 @@ public function inline_edit() {
 							 * @param array $dropdown_args An array of arguments passed to wp_dropdown_pages().
 							 * @param bool  $bulk          A flag to denote if it's a bulk action.
 							 */
-							$dropdown_args = apply_filters( 'quick_edit_dropdown_pages_args', $dropdown_args, $bulk );
+							$dropdown_args = apply_filters( 'quick_edit_dropdown_pages_args', $dropdown_args, (bool) $bulk );
 
 							wp_dropdown_pages( $dropdown_args );
 							?>
@@ -2108,12 +2108,12 @@ public function inline_edit() {
 								 *
 								 * @since 6.9.0
 								 *
-								 * @param array<string,string> $inline_edit_statuses An array of statuses available in the Quick Edit UI.
-								 * @param string               $post_type            The post type slug.
-								 * @param bool                 $bulk                 A flag to denote if it's a bulk action.
-								 * @param bool                 $can_publish          A flag to denote if the user can publish posts.
+								 * @param string[] $inline_edit_statuses An array of statuses available in the Quick Edit UI.
+								 * @param string   $post_type            The post type slug.
+								 * @param bool     $bulk                 A flag to denote if it's a bulk action.
+								 * @param bool     $can_publish          A flag to denote if the user can publish posts.
 								 */
-								$inline_edit_statuses = apply_filters( 'quick_edit_statuses', $inline_edit_statuses, $screen->post_type, $bulk, $can_publish );
+								$inline_edit_statuses = apply_filters( 'quick_edit_statuses', $inline_edit_statuses, $screen->post_type, (bool) $bulk, $can_publish );
 
 								foreach ( $inline_edit_statuses as $inline_status_value => $inline_status_text ) :
 									?>

src/wp-admin/includes/class-wp-upgrader.php

@@ -933,6 +933,7 @@ public function run( $options ) {
 				 * internally during actions, causing an error because
 				 * `WP_Upgrader::restore_temp_backup()` expects an array.
 				 */
+				// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 				add_action( 'shutdown', array( $this, 'restore_temp_backup' ), 10, 0 );
 			}
 			$this->skin->error( $result );
@@ -950,6 +951,7 @@ public function run( $options ) {
 		// Clean up the backup kept in the temporary backup directory.
 		if ( ! empty( $options['hook_extra']['temp_backup'] ) ) {
 			// Delete the backup on `shutdown` to avoid a PHP timeout.
+			// @phpstan-ignore return.void (WordPress discards an action callback's return value.)
 			add_action( 'shutdown', array( $this, 'delete_temp_backup' ), 100, 0 );
 		}
 

src/wp-admin/includes/dashboard.php

@@ -1622,7 +1622,7 @@ function wp_dashboard_primary() {
 			 *
 			 * @since 4.4.0
 			 *
-			 * @param string $items How many items to show in the secondary feed.
+			 * @param int $items How many items to show in the secondary feed.
 			 */
 			'items'        => apply_filters( 'dashboard_secondary_items', 3 ),
 			'show_summary' => 0,

src/wp-admin/includes/image.php

@@ -635,7 +635,7 @@ function wp_generate_attachment_metadata( $attachment_id, $file ) {
 					break;
 			}
 			$basename = str_replace( '.', '-', wp_basename( $file ) ) . '-image' . $ext;
-			$uploaded = wp_upload_bits( $basename, '', $metadata['image']['data'] );
+			$uploaded = wp_upload_bits( $basename, null, $metadata['image']['data'] );
 			if ( false === $uploaded['error'] ) {
 				$image_attachment = array(
 					'post_mime_type' => $metadata['image']['mime'],

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

@@ -17,6 +17,15 @@
  * @param string $class_name The type of the list table, which is the class name.
  * @param array  $args       Optional. Arguments to pass to the class. Accepts 'screen'.
  * @return WP_List_Table|false List table object on success, false if the class does not exist.
+ *
+ * @phpstan-template T of string
+ * @phpstan-param T $class_name
+ * @phpstan-param array{screen?: string|WP_Screen|null} $args
+ * @phpstan-return (
+ *     $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'
+ *         ? new<T>
+ *         : false
+ * )
  */
 function _get_list_table( $class_name, $args = array() ) {
 	$core_classes = array(

src/wp-admin/includes/media.php

@@ -211,9 +211,9 @@ function image_add_caption( $html, $id, $caption, $title, $align, $url, $size, $
 	 * @since 2.6.0
 	 *
 	 * @param bool $bool Whether to disable appending captions. Returning true from the filter
-	 *                   will disable captions. Default empty string.
+	 *                   will disable captions. Default false.
 	 */
-	if ( empty( $caption ) || apply_filters( 'disable_captions', '' ) ) {
+	if ( empty( $caption ) || apply_filters( 'disable_captions', false ) ) {
 		return $html;
 	}
 
@@ -1238,6 +1238,8 @@ function image_align_input_fields( $post, $checked = '' ) {
  * @param WP_Post     $post
  * @param bool|string $check
  * @return array<string, string> An array of data for the image size input fields.
+ *
+ * @phpstan-return array{label: string, input: 'html', html: string}
  */
 function image_size_input_fields( $post, $check = '' ) {
 	/**
@@ -1316,6 +1318,8 @@ function image_size_input_fields( $post, $check = '' ) {
  * @param WP_Post $post
  * @param string  $url_type
  * @return string HTML markup for the link URL buttons.
+ *
+ * @phpstan-return non-falsy-string
  */
 function image_link_input_fields( $post, $url_type = '' ) {
 
@@ -1349,6 +1353,8 @@ function image_link_input_fields( $post, $url_type = '' ) {
  *
  * @param WP_Post $edit_post Attachment WP_Post object.
  * @return string HTML markup for the textarea element.
+ *
+ * @phpstan-return non-falsy-string
  */
 function wp_caption_input_textarea( $edit_post ) {
 	// Post data is already escaped.
@@ -1638,6 +1644,8 @@ function get_media_items( $post_id, $errors ) {
  * @param int          $attachment_id Attachment ID for modification.
  * @param string|array $args          Optional. Override defaults.
  * @return string HTML form for attachment.
+ *
+ * @phpstan-return non-falsy-string
  */
 function get_media_item( $attachment_id, $args = null ) {
 	global $redir_tab;
@@ -1932,6 +1940,8 @@ function get_media_item( $attachment_id, $args = null ) {
  * @param int   $attachment_id
  * @param array $args
  * @return array<string, string> An array containing the media item and its metadata.
+ *
+ * @phpstan-return array{item: string, meta: string}
  */
 function get_compat_media_markup( $attachment_id, $args = null ) {
 	$post = get_post( $attachment_id );
@@ -3014,6 +3024,8 @@ function media_upload_library_form( $errors ) {
  *
  * @param string $default_view
  * @return string HTML content of the form.
+ *
+ * @phpstan-return non-falsy-string
  */
 function wp_media_insert_url_form( $default_view = 'image' ) {
 	/** This filter is documented in wp-admin/includes/media.php */

src/wp-admin/includes/menu.php

@@ -208,6 +208,11 @@
  * @param string $class_to_add The CSS class to add.
  * @param string $classes      The string to add the CSS class to.
  * @return string The string with the CSS class added.
+ *
+ * @phpstan-template T of string
+ * @phpstan-param T $class_to_add
+ * @phpstan-pure
+ * @phpstan-return ($classes is empty ? T : non-empty-string)
  */
 function add_cssclass( $class_to_add, $classes ) {
 	if ( empty( $classes ) ) {