Docs: Add PHPStan array shapes

src/wp-admin/includes/bookmark.php

@@ -56,6 +56,8 @@ function edit_link( $link_id = 0 ) {
  * @since 2.0.0
  *
  * @return stdClass Default link object.
+ *
+ * @phpstan-return object{link_url: string, link_name: string, link_visible: 'Y'}&stdClass
  */
 function get_default_link_to_edit() {
 	$link = new stdClass();
@@ -122,6 +124,8 @@ function wp_delete_link( $link_id ) {
  *
  * @param int $link_id Link ID to look up.
  * @return int[]|WP_Error The IDs of the requested link's categories, or else a WP_Error if the `link_category` taxonomy was unregistered.
+ *
+ * @phpstan-return array<int, int<1, max>>|WP_Error
  */
 function wp_get_link_cats( $link_id = 0 ) {
 	$cats = wp_get_object_terms( $link_id, 'link_category', array( 'fields' => 'ids' ) );

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

@@ -36,6 +36,7 @@
  *
  * @phpstan-template T of WP_List_Table
  * @phpstan-param class-string<T> $class_name
+ * @phpstan-param array{plural?: string, singular?: string, ajax?: bool, screen?: string|WP_Screen|null} $args
  * @phpstan-return T|false
  */
 function _get_list_table( $class_name, $args = 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 = '' ) {
 	/**
@@ -1937,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 );

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(

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/post.php

@@ -1220,6 +1220,8 @@ function _fix_attachment_links( $post ) {
  *
  * @param string $type The post_type you want the statuses for. Default 'post'.
  * @return string[] An array of all the statuses for the supplied post type.
+ *
+ * @phpstan-return list<string>
  */
 function get_available_post_statuses( $type = 'post' ) {
 	$statuses = wp_count_posts( $type );

src/wp-includes/class-wp-block-supports.php

@@ -197,6 +197,8 @@ private function register_attributes() {
  *
  * @param string[] $extra_attributes Optional. Array of extra attributes to render on the block wrapper.
  * @return string String of HTML attributes.
+ *
+ * @phpstan-param array<string, string|int|float> $extra_attributes
  */
 function get_block_wrapper_attributes( $extra_attributes = array() ) {
 	$new_attributes = WP_Block_Supports::get_instance()->apply_block_supports();

src/wp-includes/class-wp-dependencies.php

@@ -74,6 +74,8 @@ class WP_Dependencies {
 	 * @since 2.8.0
 	 *
 	 * @var (int|false)[]
+	 *
+	 * @phpstan-var array<string, int|false>
 	 */
 	public $groups = array();
 

src/wp-includes/class-wp-http.php

@@ -29,6 +29,15 @@
  * Debugging includes several actions, which pass different variables for debugging the HTTP API.
  *
  * @since 2.7.0
+ *
+ * @phpstan-type HTTP_Response array{
+ *     headers: \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array<string, string>,
+ *     body: string,
+ *     response: array{code: int|false, message: string|false},
+ *     cookies: WP_Http_Cookie[],
+ *     filename?: string|null,
+ *     http_response?: WP_HTTP_Requests_Response|null,
+ * }
  */
 #[AllowDynamicProperties]
 class WP_Http {
@@ -166,6 +175,8 @@ class WP_Http {
 	 *     @type string|null                                            $filename      Optional. Filename of the response.
 	 *     @type WP_HTTP_Requests_Response|null                         $http_response Response object.
 	 * }
+	 *
+	 * @phpstan-return HTTP_Response|WP_Error
 	 */
 	public function request( $url, $args = array() ) {
 		$defaults = array(
@@ -633,6 +644,8 @@ private function _dispatch_request( $url, $args ) {
 	 * @param string|array $args Optional. Override the defaults.
 	 * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
 	 *                        A WP_Error instance upon error. See WP_Http::response() for details.
+	 *
+	 * @phpstan-return HTTP_Response|WP_Error
 	 */
 	public function post( $url, $args = array() ) {
 		$defaults    = array( 'method' => 'POST' );
@@ -651,6 +664,8 @@ public function post( $url, $args = array() ) {
 	 * @param string|array $args Optional. Override the defaults.
 	 * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
 	 *                        A WP_Error instance upon error. See WP_Http::response() for details.
+	 *
+	 * @phpstan-return HTTP_Response|WP_Error
 	 */
 	public function get( $url, $args = array() ) {
 		$defaults    = array( 'method' => 'GET' );
@@ -669,6 +684,8 @@ public function get( $url, $args = array() ) {
 	 * @param string|array $args Optional. Override the defaults.
 	 * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
 	 *                        A WP_Error instance upon error. See WP_Http::response() for details.
+	 *
+	 * @phpstan-return HTTP_Response|WP_Error
 	 */
 	public function head( $url, $args = array() ) {
 		$defaults    = array( 'method' => 'HEAD' );

src/wp-includes/class-wp-widget.php

@@ -109,6 +109,22 @@ class WP_Widget {
 	 * @param array $args     Display arguments including 'before_title', 'after_title',
 	 *                        'before_widget', and 'after_widget'.
 	 * @param array $instance The settings for the particular instance of the widget.
+	 *
+	 * @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,
+	 *     show_in_rest?: bool,
+	 *     widget_id?: string,
+	 *     widget_name?: string,
+	 * } $args
 	 */
 	public function widget( $args, $instance ) {
 		die( 'function WP_Widget::widget() must be overridden in a subclass.' );

src/wp-includes/feed.php

@@ -599,6 +599,8 @@ function atom_enclosure() {
  *
  * @param string $data Input string.
  * @return array array(type, value)
+ *
+ * @phpstan-return array{'html'|'text'|'xhtml', string}
  */
 function prep_atom_text_construct( $data ) {
 	if ( ! str_contains( $data, '<' ) && ! str_contains( $data, '&' ) ) {

src/wp-includes/formatting.php

@@ -611,6 +611,8 @@ function wpautop( $text, $br = true ) {
  *
  * @param string $input The text which has to be formatted.
  * @return string[] Array of the formatted text.
+ *
+ * @phpstan-return non-empty-list<string>
  */
 function wp_html_split( $input ) {
 	return preg_split( get_html_split_regex(), $input, -1, PREG_SPLIT_DELIM_CAPTURE );

src/wp-includes/functions.php

@@ -8325,6 +8325,7 @@ function wp_unique_prefixed_id( $prefix = '' ) {
  * @param string $prefix Optional. A prefix to prepend to the generated ID. Default empty string.
  * @return string The generated unique ID for the array.
  *
+ * @phpstan-param non-empty-array $data
  * @phpstan-return ( $prefix is lowercase-string ? lowercase-string&non-falsy-string : non-falsy-string )
  */
 function wp_unique_id_from_values( array $data, string $prefix = '' ): string {

src/wp-includes/http.php

@@ -48,6 +48,15 @@ function _wp_http_get_object() {
  *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  *                        See WP_Http::request() for information on return value.
+ *
+ * @phpstan-return array{
+ *     headers: \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array<string, string>,
+ *     body: string,
+ *     response: array{code: int|false, message: string|false},
+ *     cookies: WP_Http_Cookie[],
+ *     filename?: string|null,
+ *     http_response?: WP_HTTP_Requests_Response|null,
+ * }|WP_Error
  */
 function wp_safe_remote_request( $url, $args = array() ) {
 	$args['reject_unsafe_urls'] = true;
@@ -77,6 +86,15 @@ function wp_safe_remote_request( $url, $args = array() ) {
  *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  *                        See WP_Http::request() for information on return value.
+ *
+ * @phpstan-return array{
+ *     headers: \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array<string, string>,
+ *     body: string,
+ *     response: array{code: int|false, message: string|false},
+ *     cookies: WP_Http_Cookie[],
+ *     filename?: string|null,
+ *     http_response?: WP_HTTP_Requests_Response|null,
+ * }|WP_Error
  */
 function wp_safe_remote_get( $url, $args = array() ) {
 	$args['reject_unsafe_urls'] = true;
@@ -106,6 +124,15 @@ function wp_safe_remote_get( $url, $args = array() ) {
  *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  *                        See WP_Http::request() for information on return value.
+ *
+ * @phpstan-return array{
+ *     headers: \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array<string, string>,
+ *     body: string,
+ *     response: array{code: int|false, message: string|false},
+ *     cookies: WP_Http_Cookie[],
+ *     filename?: string|null,
+ *     http_response?: WP_HTTP_Requests_Response|null,
+ * }|WP_Error
  */
 function wp_safe_remote_post( $url, $args = array() ) {
 	$args['reject_unsafe_urls'] = true;
@@ -135,6 +162,15 @@ function wp_safe_remote_post( $url, $args = array() ) {
  *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  *                        See WP_Http::request() for information on return value.
+ *
+ * @phpstan-return array{
+ *     headers: \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array<string, string>,
+ *     body: string,
+ *     response: array{code: int|false, message: string|false},
+ *     cookies: WP_Http_Cookie[],
+ *     filename?: string|null,
+ *     http_response?: WP_HTTP_Requests_Response|null,
+ * }|WP_Error
  */
 function wp_safe_remote_head( $url, $args = array() ) {
 	$args['reject_unsafe_urls'] = true;
@@ -162,6 +198,15 @@ function wp_safe_remote_head( $url, $args = array() ) {
  *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response array or a WP_Error on failure.
  *                        See WP_Http::request() for information on return value.
+ *
+ * @phpstan-return array{
+ *     headers: \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array<string, string>,
+ *     body: string,
+ *     response: array{code: int|false, message: string|false},
+ *     cookies: WP_Http_Cookie[],
+ *     filename?: string|null,
+ *     http_response?: WP_HTTP_Requests_Response|null,
+ * }|WP_Error
  */
 function wp_remote_request( $url, $args = array() ) {
 	$http = _wp_http_get_object();
@@ -183,6 +228,15 @@ function wp_remote_request( $url, $args = array() ) {
  *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  *                        See WP_Http::request() for information on return value.
+ *
+ * @phpstan-return array{
+ *     headers: \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array<string, string>,
+ *     body: string,
+ *     response: array{code: int|false, message: string|false},
+ *     cookies: WP_Http_Cookie[],
+ *     filename?: string|null,
+ *     http_response?: WP_HTTP_Requests_Response|null,
+ * }|WP_Error
  */
 function wp_remote_get( $url, $args = array() ) {
 	$http = _wp_http_get_object();
@@ -204,6 +258,15 @@ function wp_remote_get( $url, $args = array() ) {
  *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  *                        See WP_Http::request() for information on return value.
+ *
+ * @phpstan-return array{
+ *     headers: \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array<string, string>,
+ *     body: string,
+ *     response: array{code: int|false, message: string|false},
+ *     cookies: WP_Http_Cookie[],
+ *     filename?: string|null,
+ *     http_response?: WP_HTTP_Requests_Response|null,
+ * }|WP_Error
  */
 function wp_remote_post( $url, $args = array() ) {
 	$http = _wp_http_get_object();
@@ -225,6 +288,15 @@ function wp_remote_post( $url, $args = array() ) {
  *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  *                        See WP_Http::request() for information on return value.
+ *
+ * @phpstan-return array{
+ *     headers: \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array<string, string>,
+ *     body: string,
+ *     response: array{code: int|false, message: string|false},
+ *     cookies: WP_Http_Cookie[],
+ *     filename?: string|null,
+ *     http_response?: WP_HTTP_Requests_Response|null,
+ * }|WP_Error
  */
 function wp_remote_head( $url, $args = array() ) {
 	$http = _wp_http_get_object();

src/wp-includes/nav-menu.php

@@ -86,6 +86,8 @@ function is_nav_menu( $menu ) {
  * @global array $_wp_registered_nav_menus
  *
  * @param string[] $locations Associative array of menu location identifiers (like a slug) and descriptive text.
+ *
+ * @phpstan-param array<string, string> $locations
  */
 function register_nav_menus( $locations = array() ) {
 	global $_wp_registered_nav_menus;

src/wp-includes/robots-template.php

@@ -66,6 +66,9 @@ function wp_robots() {
  *
  * @param array $robots Associative array of robots directives.
  * @return array Filtered robots directives.
+ *
+ * @phpstan-param array<string, bool|string> $robots
+ * @phpstan-return array<string, bool|string>
  */
 function wp_robots_noindex( array $robots ) {
 	if ( ! get_option( 'blog_public' ) ) {
@@ -88,6 +91,9 @@ function wp_robots_noindex( array $robots ) {
  *
  * @param array $robots Associative array of robots directives.
  * @return array Filtered robots directives.
+ *
+ * @phpstan-param array<string, bool|string> $robots
+ * @phpstan-return array<string, bool|string>
  */
 function wp_robots_noindex_embeds( array $robots ) {
 	if ( is_embed() ) {
@@ -114,6 +120,9 @@ function wp_robots_noindex_embeds( array $robots ) {
  *
  * @param array $robots Associative array of robots directives.
  * @return array Filtered robots directives.
+ *
+ * @phpstan-param array<string, bool|string> $robots
+ * @phpstan-return array<string, bool|string>
  */
 function wp_robots_noindex_search( array $robots ) {
 	if ( is_search() ) {
@@ -136,6 +145,9 @@ function wp_robots_noindex_search( array $robots ) {
  *
  * @param array $robots Associative array of robots directives.
  * @return array Filtered robots directives.
+ *
+ * @phpstan-param array<string, bool|string> $robots
+ * @phpstan-return array<string, bool|string>
  */
 function wp_robots_no_robots( array $robots ) {
 	$robots['noindex'] = true;
@@ -163,6 +175,9 @@ function wp_robots_no_robots( array $robots ) {
  *
  * @param array $robots Associative array of robots directives.
  * @return array Filtered robots directives.
+ *
+ * @phpstan-param array<string, bool|string> $robots
+ * @phpstan-return array<string, bool|string>
  */
 function wp_robots_sensitive_page( array $robots ) {
 	$robots['noindex']   = true;
@@ -184,6 +199,9 @@ function wp_robots_sensitive_page( array $robots ) {
  *
  * @param array $robots Associative array of robots directives.
  * @return array Filtered robots directives.
+ *
+ * @phpstan-param array<string, bool|string> $robots
+ * @phpstan-return array<string, bool|string>
  */
 function wp_robots_max_image_preview_large( array $robots ) {
 	if ( get_option( 'blog_public' ) ) {