Docs: Bring the PHPStan types from the WordPress stubs' function map into core

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/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/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

@@ -1237,6 +1237,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 = '' ) {
 	/**
@@ -1315,6 +1317,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 = '' ) {
 
@@ -1348,6 +1352,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.
@@ -1637,6 +1643,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;
@@ -1931,6 +1939,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 );
@@ -3013,6 +3023,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 ) ) {

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

@@ -1257,6 +1257,8 @@ function link_target_meta_box( $link ) {
  *                                 if it matches the current link's relationship.
  *                                 Default empty string.
  * @param mixed  $deprecated       Deprecated. Not used.
+ *
+ * @phpstan-param '' $deprecated
  */
 function xfn_check( $xfn_relationship, $xfn_value = '', $deprecated = '' ) {
 	global $link;

src/wp-admin/includes/ms.php

@@ -1187,6 +1187,8 @@ function network_edit_site_nav( $args = array() ) {
  * @since 4.9.0
  *
  * @return array Help tab arguments.
+ *
+ * @phpstan-return array{id: 'overview', title: string, content: non-falsy-string}
  */
 function get_site_screen_help_tab_args() {
 	return array(
@@ -1211,6 +1213,8 @@ function get_site_screen_help_tab_args() {
  * @since 4.9.0
  *
  * @return string Help sidebar content.
+ *
+ * @phpstan-return non-falsy-string
  */
 function get_site_screen_help_sidebar_content() {
 	return '<p><strong>' . __( 'For more information:' ) . '</strong></p>' .

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

@@ -1348,6 +1348,16 @@ function wp_get_nav_menu_to_edit( $menu_id = 0 ) {
  * @since 3.0.0
  *
  * @return string[] Array of column titles keyed by their column name.
+ *
+ * @phpstan-return array{
+ *     _title: string,
+ *     cb: '<input type="checkbox" />',
+ *     link-target: string,
+ *     title-attribute: string,
+ *     css-classes: string,
+ *     xfn: string,
+ *     description: string,
+ * }
  */
 function wp_nav_menu_manage_columns() {
 	return array(

src/wp-admin/includes/plugin-install.php

@@ -309,6 +309,8 @@ function install_dashboard() {
  * @since 4.6.0 The `$type_selector` parameter was deprecated.
  *
  * @param bool $deprecated Not used.
+ *
+ * @phpstan-param true $deprecated
  */
 function install_search_form( $deprecated = true ) {
 	$type = isset( $_REQUEST['type'] ) ? wp_unslash( $_REQUEST['type'] ) : 'term';