Context Navigation

← Previous Change
Next Change →

class-wp-post.php

Timestamp:

07/06/2026 08:53:46 PM (30 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.

File:

: 1 edited

trunk/src/wp-includes/class-wp-post.php (modified) (8 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 );

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

Make WordPress Core

Context Navigation

Changeset 62648 for trunk/src/wp-includes/class-wp-post.php

Legend:

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

Download in other formats: