Code Quality: Improve WP_Post type coverage.

Add a `Data_Array` array-shape type describing every key returned by `WP_Post::to_array()`, and tighten each `WP_Post` property to the narrowest type the schema and code guarantee:

* `ID` and `post_parent` become `non-negative-int`.
* `comment_count` becomes `numeric-string`, and `post_author` becomes `numeric-string|''` (a user ID, or an empty string for a default post that has not yet been assigned an author).
* The always-populated `post_status`, `comment_status`, `ping_status`, and `post_type` slugs become `non-empty-string`, left open rather than enumerated so custom statuses and types remain valid.
* The magic `ancestors`, `post_category`, and `tags_input` accessors become precise lists (`list<non-negative-int>` and `list<non-empty-string>`).

The shape stays open because `WP_Post` permits dynamic properties. Fields that can legitimately be empty, including the datetime fields (which `get_default_post_to_edit()` may leave empty), stay `string`, and `menu_order` stays `int` since it can be negative.

Correct `WP_Post::$filter`, which was previously typed without `null` or the `'sample'` context: an unsanitized post has no `filter` (checked in core via `isset()` and `empty()`), and `get_sample_permalink()` has assigned `'sample'` since [8526]. Widen `sanitize_post_field()`'s `$context` to accept `'sample'` to match, which it already treats as a `'display'` context.

Also type `get_post_ancestors()` as returning `list<non-negative-int>`, read the post in `trackback_url_list()` via `to_array()` while guarding against a missing post, and cast `post_author` to a string in `WP_Customize_Nav_Menu_Item_Setting` and `inject_ignored_hooked_blocks_metadata_attributes()`, which each populate an object before passing it to `new WP_Post()`.

Developed in WordPress#12491.
Follow-up to r62648, r62694.

See #64898, #64896.


git-svn-id: https://develop.svn.wordpress.org/trunk@62717 602fd350-edb4-49c9-b593-d223f7449a82

Author: westonruter

src/wp-includes/block-template-utils.php

@@ -1739,9 +1739,15 @@ function inject_ignored_hooked_blocks_metadata_attributes( $changes, $deprecated
 	// Required for the WP_Block_Template. Update the post object with the current time.
 	$post->post_modified = current_time( 'mysql' );
 
-	// If the post_author is empty, set it to the current user.
+	/*
+	 * If the post_author is empty, set it to the current user. If it arrived as
+	 * an int (e.g. from a REST controller), normalize it to a string, since the
+	 * resulting object is passed to new WP_Post().
+	 */
 	if ( empty( $post->post_author ) ) {
-		$post->post_author = get_current_user_id();
+		$post->post_author = (string) get_current_user_id();
+	} elseif ( is_int( $post->post_author ) ) {
+		$post->post_author = (string) $post->post_author;
 	}
 
 	if ( 'wp_template_part' === $post->post_type && ! isset( $terms['wp_template_part_area'] ) ) {

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

@@ -14,9 +14,41 @@
  *
  * @property string $page_template
  *
- * @property-read int[]    $ancestors
- * @property-read int[]    $post_category
- * @property-read string[] $tags_input
+ * @property-read list<non-negative-int> $ancestors
+ * @property-read list<non-negative-int> $post_category
+ * @property-read list<non-empty-string> $tags_input
+ *
+ * @phpstan-type Data_Array array{
+ *     ID: non-negative-int,
+ *     post_author: numeric-string|'',
+ *     post_date: string,
+ *     post_date_gmt: string,
+ *     post_content: string,
+ *     post_title: string,
+ *     post_excerpt: string,
+ *     post_status: non-empty-string,
+ *     comment_status: non-empty-string,
+ *     ping_status: non-empty-string,
+ *     post_password: string,
+ *     post_name: string,
+ *     to_ping: string,
+ *     pinged: string,
+ *     post_modified: string,
+ *     post_modified_gmt: string,
+ *     post_content_filtered: string,
+ *     post_parent: non-negative-int,
+ *     guid: string,
+ *     menu_order: int,
+ *     post_type: non-empty-string,
+ *     post_mime_type: string,
+ *     comment_count: numeric-string,
+ *     filter: 'raw'|'edit'|'db'|'display'|'attribute'|'js'|'sample'|null,
+ *     ancestors: list<non-negative-int>,
+ *     page_template: string,
+ *     post_category: list<non-negative-int>,
+ *     tags_input: list<non-empty-string>,
+ *     ...
+ * }
  */
 #[AllowDynamicProperties]
 final class WP_Post {
@@ -26,17 +58,19 @@ final class WP_Post {
 	 *
 	 * @since 3.5.0
 	 * @var int
+	 * @phpstan-var non-negative-int
 	 */
 	public $ID;
 
 	/**
 	 * ID of post author.
 	 *
-	 * A numeric string, for compatibility reasons.
+	 * A numeric string, for compatibility reasons. May be an empty string for a
+	 * default post that has not yet been assigned an author.
 	 *
 	 * @since 3.5.0
 	 * @var string
-	 * @phpstan-var numeric-string
+	 * @phpstan-var numeric-string|''
 	 */
 	public $post_author = '0';
 
@@ -85,6 +119,7 @@ final class WP_Post {
 	 *
 	 * @since 3.5.0
 	 * @var string
+	 * @phpstan-var non-empty-string
 	 */
 	public $post_status = 'publish';
 
@@ -93,6 +128,7 @@ final class WP_Post {
 	 *
 	 * @since 3.5.0
 	 * @var string
+	 * @phpstan-var non-empty-string
 	 */
 	public $comment_status = 'open';
 
@@ -101,6 +137,7 @@ final class WP_Post {
 	 *
 	 * @since 3.5.0
 	 * @var string
+	 * @phpstan-var non-empty-string
 	 */
 	public $ping_status = 'open';
 
@@ -165,6 +202,7 @@ final class WP_Post {
 	 *
 	 * @since 3.5.0
 	 * @var int
+	 * @phpstan-var non-negative-int
 	 */
 	public $post_parent = 0;
 
@@ -189,6 +227,7 @@ final class WP_Post {
 	 *
 	 * @since 3.5.0
 	 * @var string
+	 * @phpstan-var non-empty-string
 	 */
 	public $post_type = 'post';
 
@@ -216,9 +255,11 @@ final class WP_Post {
 	 *
 	 * Does not correspond to a DB field.
 	 *
+	 * The 'sample' value is set exclusively by {@see get_sample_permalink()} and is read during permalink previewing.
+	 *
 	 * @since 3.5.0
-	 * @var string
-	 * @phpstan-var 'raw'|'edit'|'db'|'display'|'attribute'|'js'
+	 * @var string|null
+	 * @phpstan-var 'raw'|'edit'|'db'|'display'|'attribute'|'js'|'sample'|null
 	 */
 	public $filter;
 
@@ -389,10 +430,9 @@ public function filter( $filter ) {
 	 *
 	 * @return array<string, mixed> Object as array.
 	 *
-	 * @phpstan-return non-empty-array<string, mixed>
+	 * @phpstan-return Data_Array
 	 */
 	public function to_array() {
-		/** @var non-empty-array<string, mixed> $post */
 		$post = get_object_vars( $this );
 
 		foreach ( array( 'ancestors', 'page_template', 'post_category', 'tags_input' ) as $key ) {
@@ -401,6 +441,7 @@ public function to_array() {
 			}
 		}
 
+		/** @var Data_Array $post */
 		return $post;
 	}
 }

src/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php

@@ -625,7 +625,7 @@ public function value_as_wp_post_nav_menu_item() {
 		$post        = new WP_Post( (object) $item );
 
 		if ( empty( $post->post_author ) ) {
-			$post->post_author = get_current_user_id();
+			$post->post_author = (string) get_current_user_id();
 		}
 
 		if ( ! isset( $post->type_label ) ) {

src/wp-includes/post.php

@@ -1185,6 +1185,7 @@ function get_post( $post = null, $output = OBJECT, $filter = 'raw' ) {
  *
  * @param int|WP_Post $post Post ID or post object.
  * @return int[] Array of ancestor IDs or empty array if there are none.
+ * @phpstan-return list<non-negative-int>
  */
 function get_post_ancestors( $post ) {
 	$post = get_post( $post );
@@ -3001,19 +3002,20 @@ function sanitize_post( $post, $context = 'display' ) {
  *
  * Possible context values are:  'raw', 'edit', 'db', 'display', 'attribute' and
  * 'js'. The 'display' context is used by default. 'attribute' and 'js' contexts
- * are treated like 'display' when calling filters.
+ * are treated like 'display' when calling filters. The 'sample' value is used
+ * for permalink previewing.
  *
  * @since 2.3.0
  * @since 4.4.0 Like `sanitize_post()`, `$context` defaults to 'display'.
  *
  * @param string $field   The Post Object field name.
  * @param mixed  $value   The Post Object value.
  * @param int    $post_id Post ID.
- * @param string $context Optional. How to sanitize the field. Possible values are 'raw', 'edit',
- *                        'db', 'display', 'attribute' and 'js'. Default 'display'.
+ * @param string $context Optional. How to sanitize the field. Possible values are 'raw', 'edit', 'db', 'display',
+ *                        'attribute' and 'js'. The 'sample' value is used for permalink previewing. Default 'display'.
  * @return mixed Sanitized value.
  *
- * @phpstan-param 'raw'|'edit'|'db'|'display'|'attribute'|'js' $context
+ * @phpstan-param 'raw'|'edit'|'db'|'display'|'attribute'|'js'|'sample' $context
  * @phpstan-return (
  *     $field is 'ID'|'post_parent'|'menu_order' ? int : (
  *         $field is 'ancestors' ? non-negative-int[] : string
@@ -3286,7 +3288,8 @@ function sanitize_post_field( $field, $value, $post_id, $context = 'display' ) {
 			 * @param int    $post_id Post ID.
 			 * @param string $context Context for how to sanitize the field.
 			 *                        Accepts 'raw', 'edit', 'db', 'display',
-			 *                        'attribute', or 'js'. Default 'display'.
+			 *                        'attribute', or 'js'. The 'sample' value is
+			 *                        used for permalink previewing. Default 'display'.
 			 */
 			$value = apply_filters( "{$field}", $value, $post_id, $context );
 		} else {
@@ -3313,7 +3316,8 @@ function sanitize_post_field( $field, $value, $post_id, $context = 'display' ) {
 			 * @param int    $post_id Post ID
 			 * @param string $context Context for how to sanitize the field.
 			 *                        Accepts 'raw', 'edit', 'db', 'display',
-			 *                        'attribute', or 'js'. Default 'display'.
+			 *                        'attribute', or 'js'. The 'sample' value is
+			 *                        used for permalink previewing. Default 'display'.
 			 */
 			$value = apply_filters( "post_{$field}", $value, $post_id, $context );
 		}
@@ -6149,11 +6153,11 @@ function get_to_ping( $post ) {
 function trackback_url_list( $tb_list, $post_id ) {
 	if ( ! empty( $tb_list ) ) {
 		// Get post data.
-		$postdata = get_post( $post_id, ARRAY_A );
-
-		if ( ! $postdata ) {
+		$post = get_post( $post_id );
+		if ( ! $post ) {
 			return;
 		}
+		$postdata = $post->to_array();
 
 		// Form an excerpt.
 		$excerpt = strip_tags( $postdata['post_excerpt'] ? $postdata['post_excerpt'] : $postdata['post_content'] );

tests/phpunit/tests/customize/nav-menu-item-setting.php

@@ -950,7 +950,7 @@ public function test_value_as_wp_post_nav_menu_item() {
 		$this->assertSame( $post_value['title'], $nav_menu_item->post_title );
 		$this->assertSame( 123, $nav_menu_item->ID );
 		$this->assertSame( 123, $nav_menu_item->db_id );
-		$this->assertSame( wp_get_current_user()->ID, $nav_menu_item->post_author );
+		$this->assertSame( (string) wp_get_current_user()->ID, $nav_menu_item->post_author );
 		$this->assertObjectHasProperty( 'type_label', $nav_menu_item );
 		$expected = apply_filters( 'nav_menu_attr_title', wp_unslash( apply_filters( 'excerpt_save_pre', wp_slash( $post_value['attr_title'] ) ) ) );
 		$this->assertSame( $expected, $nav_menu_item->attr_title );