Posts, Post Types: Add conditional return types to post retrieval, sanitization, and insertion functions

[westonruter]

Adds precise, conditional PHPStan return types to the core post retrieval, sanitization, and insertion APIs, along with a small amount of behavior-preserving runtime hardening (and one genuine latent-bug fix) that these types surfaced.

Conditional return types

Functions whose return type depends on an argument now carry a @phpstan-return keyed on that argument, so static analysis can narrow the result at each call site:

• get_post(), get_page(), get_page_by_path() — keyed on $output: array<string, mixed>|null for ARRAY_A, array<int, mixed>|null for ARRAY_N, WP_Post|null otherwise.
• get_children() — keyed first on $args['fields'] ('ids' → int[], mirroring get_posts()) and then on $output.
• get_posts() and WP_Query::query() — $args with fields => 'ids' → int[], otherwise WP_Post[].
• wp_get_recent_posts() — ARRAY_A → array<int, array<string, mixed>>, otherwise WP_Post[]|false.
• get_post_field() / sanitize_post_field() — keyed on $field: int for ID/post_parent/menu_order, non-negative-int[] for ancestors, string otherwise (get_post_field() additionally includes the '' failure return).
• sanitize_post() — same type in as out (WP_Post, stdClass, or array).
• get_post_types() — 'names' → string[], otherwise WP_Post_Type[].
• wp_insert_post(), wp_update_post(), wp_insert_attachment() — $wp_error === false → int, otherwise int|WP_Error.

Matching @phpstan-param tags were added where the analyzed return depends on a narrowed input (e.g. $output, $context, $filter).

Runtime changes

Most of the diff is documentation-only, but a few small code changes were needed for the types to hold:

• get_post() now null-guards the WP_Post::filter( 'raw' ) result. filter( 'raw' ) calls WP_Post::get_instance(), which can return false for a since-deleted post; the previous code would then call ->to_array() on false. This is a real latent fix, not just a typing change. WP_Post::filter() is retyped WP_Post|false accordingly and its missing summary docblock is filled in.
• WP_Post::get_instance() cache-hit guard uses instanceof stdClass/instanceof WP_Post (behavior-preserving vs. the old truthiness check) and casts $_post->ID to int before caching.
• get_post() routes non-numeric scalar $post values straight to null instead of issuing a pointless WHERE ID = 0 query.
• sanitize_post_field() casts $value to array before array_map( 'absint', ... ) for the ancestors field.
• WP_Post::get_category() / get_tags() guard against a WP_Error from get_the_terms().
• Assorted (int) casts on post IDs passed to get_post()/get_instance().

Verified with phpstan-diff against trunk: no new errors on changed lines.

Trac ticket: https://core.trac.wordpress.org/ticket/64898

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 4.8
Used for: Drafting the conditional return type annotations and the accompanying runtime hardening under my direction. I reviewed, tested, and take responsibility for all of the changes.

---

✅ Committed in r62648 (578d09b)

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[westonruter]

PHPStan impact: trunk → this branch

Ran two full PHPStan passes (local phpstan.neon, level 10) on trunk and on this branch to quantify the effect.

Metric	Value
Errors in trunk	34,431
Errors in this branch	34,149
Net change	−282
Fixed	310
Introduced	28
% of baseline fixed	0.90%
Net reduction	0.82%

Reconciliation checks out: 310 − 28 = 282. A 0.82% net reduction from a mostly-annotation diff — the precise return types let PHPStan resolve mixed/object returns at hundreds of downstream call sites. Top beneficiaries: post.php (−64), class-wp-xmlrpc-server.php (−52), media.php (−15), ajax-actions.php/admin/post.php/class-wp-customize-nav-menus.php (−12 each).

Errors fixed by identifier (310)

Count	Identifier
110	property.nonObject
77	argument.type
75	offsetAccess.nonOffsetAccessible
13	encapsedStringPart.nonString
9	missingType.iterableValue
8	return.type
7	assign.propertyType
4	offsetAccess.invalidOffset
3	property.notFound
3	method.nonObject
1	binaryOp.invalid

Triage of the 28 "introduced"

None are regressions in the changed code, with one known-trade-off exception. They fall into four buckets:

1. Latent call-site bugs exposed by sharper types (~15). Since get_post() / get_page_by_path() now return array|WP_Post|null precisely (instead of mixed/object), PHPStan can finally see call sites that assume a bare WP_Post:

• media.php (5) and class-wp-customize-nav-menus.php (7): Cannot access property $ID/$post_title on array|WP_Post|null, expects WP_Post, array|WP_Post|null given.
• class-wp-query.php (1): passes mixed to get_page_by_path()'s now-typed $post_type.

These are pre-existing fragilities (unchecked null, ignored ARRAY_A case) surfaced by the new types — good candidates for follow-up under this same ticket rather than expanding this PR.

2. Dead-check / unused-type warnings that are artifacts of the narrowed types (3):

• WP_Post::get_instance() — empty( $_post->filter ) flagged because $filter is now the 'raw'|'edit'|… enum (never falsy); it's a defensive check.
• nav-menu.php — isset() on the non-nullable WP_Post::$ID.
• _fix_attachment_links() — return.unusedType, because precise types made a WP_Error branch provably unreachable.

3. Genuine imprecision in this branch's annotation (2):

post.php — sanitize_post_field() should return array<int<0, max>>|int|string but returns mixed  (×2)

The 'raw' context returns $value unchanged (mixed), but the conditional return declares string for that field class. In practice raw DB values are strings, but PHPStan can't prove it. Leaving this as a deliberate precision-vs-soundness trade-off; the net result is still −282.

4. Nondeterministic churn unrelated to the diff (~7). The WP_Taxonomy (upgrade.php, block-template-utils.php), wp-mail.php, and Twenty Fourteen entries — verified the totals are identical before/after (e.g. WP_Taxonomy-related errors are 260 in both runs), just redistributed between passes. None of that code is touched here.

---

_{Analysis performed by Claude (Opus 4.8) via Claude Code, at the request of and reviewed by @westonruter.}