Context Navigation

← Previous Changeset
Next Changeset →

Changeset 62648

Timestamp:

07/06/2026 08:53:46 PM (28 hours ago)

Author:

westonruter

Message:

Code Quality: Add conditional return types to post functions.

Annotate the core post retrieval, sanitization, and insertion APIs with PHPStan conditional return types keyed on their mode arguments, so static analysis can resolve the concrete result at each call site:

get_post(), get_page(), get_page_by_path(), get_children(), and get_post_types() narrow on $output.
get_posts() and WP_Query::query() narrow on the fields argument.
get_post_field() and sanitize_post_field() narrow on $field.
wp_insert_post(), wp_update_post(), and wp_insert_attachment() narrow on $wp_error.

Matching @phpstan-param tags are added where the analyzed return depends on a narrowed input.

Separately, several previously generic or underspecified types are filled in where the precise type is known:

WP_Post::to_array() is typed array<string, mixed> rather than a bare array.
WP_Post::$filter is annotated with its recognized context values rather than a bare string.
WP_Post::filter() is corrected to return WP_Post|false (previously WP_Post), and its missing summary is documented.
sanitize_post()'s $post parameter is narrowed from object to stdClass|WP_Post.

Because these functions were previously typed as returning mixed or a bare object, the sharper types let analysis see through to hundreds of downstream call sites, for a net reduction of roughly 280 PHPStan errors across the tree.

A few supporting runtime changes make the types hold:

get_post() now guards against the false that WP_Post::filter( 'raw' ) can return for a since-deleted post.
WP_Post::get_instance() tightens its cache-hit check.
post IDs are cast to int where passed on.

Developed in https://github.com/WordPress/wordpress-develop/pull/12426.
Follow-up to r61789.

See #64898, #64896.

Location:

trunk/src/wp-includes

Files:

: 3 edited

class-wp-post.php (modified) (8 diffs)
class-wp-query.php (modified) (1 diff)
post.php (modified) (24 diffs)

Legend:

: Unmodified
: Added
: Removed

trunk/src/wp-includes/class-wp-post.php

-              r62437
+              r62648
          * @since 3.5.0
          * @var string
+         * @phpstan-var 'raw'|'edit'|'db'|'display'|'attribute'|'js'
          */
         public $filter;
 …
          * @param int $post_id Post ID.
          * @return WP_Post|false Post object, false otherwise.
+         *
+         * @phpstan-param int|numeric-string $post_id
          */
         public static function get_instance( $post_id ) {
 …
                 $_post = wp_cache_get( $post_id, 'posts' );
                 if ( ! $_post ) {
+                if ( ! ( $_post instanceof stdClass ) && ! ( $_post instanceof WP_Post ) ) {
                         $_post = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = %d LIMIT 1", $post_id ) );
 …
                         $_post = sanitize_post( $_post, 'raw' );
                         wp_cache_add( $_post->ID, $_post, 'posts' );
+                        wp_cache_add( (int) $_post->ID, $_post, 'posts' );
                 } elseif ( empty( $_post->filter ) || 'raw' !== $_post->filter ) {
                         $_post = sanitize_post( $_post, 'raw' );
 …
+                        }
                         if ( empty( $terms ) ) {
+                        if ( empty( $terms ) || $terms instanceof WP_Error ) {
                                 return array();
+                        }
 …
+                        }
                         if ( empty( $terms ) ) {
+                        if ( empty( $terms ) || $terms instanceof WP_Error ) {
                                 return array();
+                        }
 …
         /**
+         * {@Missing Summary}
+         * Applies the provided context filter for the current post.
+         *
+         * If the requested filter was already applied, then it returns without any changes.
+         *
+         * If the 'raw' filter is supplied, then a new instance of the post is obtained and this method _may_ return false
+         * in case the underlying post was deleted.
+         *
          * @since 3.5.0
+         *
          * @param string $filter Filter.
+         * @return WP_Post
+         * @return WP_Post|false
+         *
+         * @phpstan-param 'raw'|'edit'|'db'|'display'|'attribute'|'js' $filter
+         * @phpstan-return (
+         *     $filter is 'raw' ? WP_Post|false : WP_Post
+         * )
          */
         public function filter( $filter ) {
 …
          * @since 3.5.0
+         *
          * @return array Object as array.
+         * @return array<string, mixed> Object as array.
          */
         public function to_array() {
+                /** @var array<string, mixed> $post */
                 $post = get_object_vars( $this );

trunk/src/wp-includes/class-wp-query.php

-              r62476
+              r62648
          * @param string|array $query URL query string or array of query arguments.
          * @return WP_Post[]|int[] Array of post objects or post IDs.
+         *
+         * @phpstan-return (
+         *     $query is array{ fields: 'ids', ... } ? int[] : WP_Post[]
+         * )
          */
         public function query( $query ) {

trunk/src/wp-includes/post.php

-              r62623
+              r62648
  *                       respectively. Default OBJECT.
  * @return WP_Post[]|array[]|int[] Array of post objects, arrays, or IDs, depending on `$output`.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-return (
+ *     $args is array{ fields: 'ids', ... } ? int[] : (
+ *         $output is 'ARRAY_A' ? array<int, array<string, mixed>> : (
+ *             $output is 'ARRAY_N' ? array<int, array<int, mixed>> : WP_Post[]
+ *         )
+ *     )
+ * )
  */
 function get_children( $args = '', $output = OBJECT ) {
 …
  * @return WP_Post|array|null Type corresponding to $output on success or null on failure.
  *                            When $output is OBJECT, a `WP_Post` instance is returned.
+ *
+ * @phpstan-param int|numeric-string|WP_Post|null $post
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-param 'raw'|'edit'|'db'|'display' $filter
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? array<string, mixed>|null : (
+ *         $output is 'ARRAY_N' ? array<int, mixed>|null : (
+ *             WP_Post|null
+ *         )
+ *     )
+ * )
  */
 function get_post( $post = null, $output = OBJECT, $filter = 'raw' ) {
 …
                 $_post = $post;
         } elseif ( is_object( $post ) ) {
+                /** @var stdClass $post */
                 if ( empty( $post->filter ) ) {
                         $_post = sanitize_post( $post, 'raw' );
 …
                         $_post = new WP_Post( $post );
                 } elseif ( isset( $post->ID ) ) {
                         $_post = WP_Post::get_instance( $post->ID );
+                        $_post = WP_Post::get_instance( (int) $post->ID );
                 } else {
                         $_post = null;
+                }
+        } elseif ( is_numeric( $post ) ) {
+                $_post = WP_Post::get_instance( (int) $post );
         } else {
                 $_post = WP_Post::get_instance( $post );
+                $_post = null;
+        }
 …
         $_post = $_post->filter( $filter );
+        if ( ! $_post ) {
+                return null;
+        }
         if ( ARRAY_A === $output ) {
 …
  *                             or 'display'. Default 'display'.
  * @return int|string|int[] The value of the post field on success, empty string on failure.
+ *
+ * @phpstan-param 'raw'|'edit'|'db'|'display' $context
+ * @phpstan-return (
+ *     $field is 'ID'|'post_parent'|'menu_order' ? int|'' : (
+ *         $field is 'ancestors' ? non-negative-int[]|'' : string
+ *     )
+ * )
  */
 function get_post_field( $field, $post = null, $context = 'display' ) {
 …
  *                               must match; 'not' means no elements may match. Default 'and'.
  * @return string[]|WP_Post_Type[] An array of post type names or objects.
+ * @phpstan-return ( $output is 'names' ? string[] : WP_Post_Type[] )
  */
 function get_post_types( $args = array(), $output = 'names', $operator = 'and' ) {
 …
  * }
  * @return WP_Post[]|int[] Array of post objects or post IDs.
+ *
+ * @phpstan-return (
+ *     $args is array{ fields: 'ids', ... } ? int[] : WP_Post[]
+ * )
  */
 function get_posts( $args = null ) {
 …
  * @return object|WP_Post|array The now sanitized post object or array (will be the
  *                              same type as `$post`).
+ *
+ * @phpstan-param stdClass|WP_Post|array<string, mixed> $post
+ * @phpstan-param 'raw'|'edit'|'db'|'display'|'attribute'|'js' $context
+ * @phpstan-return (
+ *     $post is WP_Post ? WP_Post : (
+ *         $post is stdClass ? stdClass : array<string, mixed>
+ *     )
+ * )
  */
 function sanitize_post( $post, $context = 'display' ) {
 …
+                }
                 foreach ( array_keys( get_object_vars( $post ) ) as $field ) {
                         $post->$field = sanitize_post_field( $field, $post->$field, $post->ID, $context );
+                        $post->$field = sanitize_post_field( $field, $post->$field, (int) $post->ID, $context );
+                }
                 $post->filter = $context;
 …
+                }
                 foreach ( array_keys( $post ) as $field ) {
                         $post[ $field ] = sanitize_post_field( $field, $post[ $field ], $post['ID'], $context );
+                        $post[ $field ] = sanitize_post_field( $field, $post[ $field ], (int) $post['ID'], $context );
+                }
                 $post['filter'] = $context;
 …
  *                        'db', 'display', 'attribute' and 'js'. Default 'display'.
  * @return mixed Sanitized value.
+ *
+ * @phpstan-param 'raw'|'edit'|'db'|'display'|'attribute'|'js' $context
+ * @phpstan-return (
+ *     $field is 'ID'|'post_parent'|'menu_order' ? int : (
+ *         $field is 'ancestors' ? non-negative-int[] : string
+ *     )
+ * )
  */
 function sanitize_post_field( $field, $value, $post_id, $context = 'display' ) {
 …
         $array_int_fields = array( 'ancestors' );
         if ( in_array( $field, $array_int_fields, true ) ) {
                 $value = array_map( 'absint', $value );
+                $value = array_map( 'absint', (array) $value );
                 return $value;
+        }
 …
  * @return array|false Array of recent posts, where the type of each element is determined
  *                     by the `$output` parameter. Empty array on failure.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A' $output
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? array<int, array<string, mixed>> : WP_Post[]|false
+ * )
  */
 function wp_get_recent_posts( $args = array(), $output = ARRAY_A ) {
 …
         );
+        /** @var array{ fields: null, ... } $parsed_args */
         $parsed_args = wp_parse_args( $args, $defaults );
 …
         if ( ARRAY_A === $output ) {
                 foreach ( $results as $key => $result ) {
+                        $results[ $key ] = get_object_vars( $result );
+                        /** @var array<string, mixed> $object_vars */
+                        $object_vars     = get_object_vars( $result );
+                        $results[ $key ] = $object_vars;
+                }
                 return $results ? $results : array();
 …
  * @param bool  $fire_after_hooks Optional. Whether to fire the after insert hooks. Default true.
  * @return int|WP_Error The post ID on success. The value 0 or WP_Error on failure.
+ *
+ * @phpstan-return (
+ *     $wp_error is false ? int : int|WP_Error
+ * )
  */
 function wp_insert_post( $postarr, $wp_error = false, $fire_after_hooks = true ) {
 …
  * @param bool         $fire_after_hooks Optional. Whether to fire the after insert hooks. Default true.
  * @return int|WP_Error The post ID on success. The value 0 or WP_Error on failure.
+ *
+ * @phpstan-return (
+ *     $wp_error is false ? int : int|WP_Error
+ * )
  */
 function wp_update_post( $postarr = array(), $wp_error = false, $fire_after_hooks = true ) {
 …
  *                            'edit', 'db', 'display'. Default 'raw'.
  * @return WP_Post|array|null WP_Post or array on success, null on failure.
+ *
+ * @phpstan-param int|numeric-string|WP_Post|null $page
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-param 'raw'|'edit'|'db'|'display' $filter
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? array<string, mixed>|null : (
+ *         $output is 'ARRAY_N' ? array<int, mixed>|null : (
+ *             WP_Post|null
+ *         )
+ *     )
+ * )
  */
 function get_page( $page, $output = OBJECT, $filter = 'raw' ) {
 …
  * @param string|array $post_type Optional. Post type or array of post types. Default 'page'.
  * @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
+ *
+ * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output
+ * @phpstan-param string|string[]              $post_type
+ * @phpstan-return (
+ *     $output is 'ARRAY_A' ? array<string, mixed>|null : (
+ *         $output is 'ARRAY_N' ? array<int, mixed>|null : (
+ *             WP_Post|null
+ *         )
+ *     )
+ * )
  */
 function get_page_by_path( $page_path, $output = OBJECT, $post_type = 'page' ) {
 …
                         return null;
                 } else {
                         return get_post( $cached, $output );
+                        return get_post( (int) $cached, $output );
+                }
+        }
 …
         ";
+        $pages = $wpdb->get_results( $sql, OBJECT_K );
+        /** @var array<object{ ID: string, post_name: string, post_parent: string, post_type: string }> $pages */
+        $pages = $wpdb->get_results( $sql, OBJECT_K ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The escaping has been applied above via esc_sql().
         $revparts = array_reverse( $parts );
 …
         if ( $found_id ) {
                 return get_post( $found_id, $output );
+                return get_post( (int) $found_id, $output );
+        }
 …
  * @param bool         $fire_after_hooks Optional. Whether to fire the after insert hooks. Default true.
  * @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure.
+ *
+ * @phpstan-return (
+ *     $wp_error is false ? int : int|WP_Error
+ * )
  */
 function wp_insert_attachment( $args, $file = false, $parent_post_id = 0, $wp_error = false, $fire_after_hooks = true ) {

Note: See TracChangeset for help on using the changeset viewer.

Make WordPress Core