Docs: Document hooks that may pass a null post object by westonruter · Pull Request #15257 · WordPress/wordpress-develop

westonruter · 2026-10-30T17:59:39Z

✅ Committed in r65075 (9865c4a).

Several hooks document their post parameter as WP_Post even though they can pass null. Callbacks that type-hint WP_Post for these parameters fatal with a TypeError when that happens. This was reported for the Image Placeholders plugin in WordPress/performance#2742, where YARPP's settings preview filters post_thumbnail_id to an ID with no post.

Hooks now documented as passing WP_Post|null:

wp_get_attachment_image_attributes: wp_get_attachment_image() only checks that wp_get_attachment_image_src() succeeded, never that get_post( $attachment_id ) found a post.
post_password_required: post_password_required() doesn't check get_post(), and a null post reaches the filter through the empty( $post->post_password ) early return, e.g. when called outside the loop.
the_password_form: get_the_password_form() explicitly handles a missing post and then passes it to the filter as is.
media_view_settings and media_view_strings: wp_enqueue_media() initializes $post to null and only looks one up when a post arg is passed, so they get null on the Media Library screen, for example.

The wording follows the existing "or null if no post is found" used by the get_the_modified_date and get_the_modified_time filters.

Core and bundled theme callbacks of these hooks are updated to match:

WP_REST_Posts_Controller::check_password_required() (also fixes "been" → "being").
WP_Abilities_Content::allow_password_content(), narrowed from mixed to the filter contract (bool, WP_Post|null). No native type hints are added, since a non-bool returned by an earlier callback would then fatal.
The wp_get_attachment_image_attributes callbacks in Twenty Sixteen, Twenty Seventeen, and Twenty Twenty-One, and Twenty Twenty-One's the_password_form callback.

All other hooks in wp-includes and wp-admin documenting a WP_Post parameter were checked; they either guard against null before the hook fires or already dereference the post earlier.

Trac ticket: Core-65860

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Auditing hook docblocks for parameters that can be null, drafting the docblock changes beyond the initial wp_get_attachment_image_attributes fix, and writing this description; changes were reviewed and directed by me.

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

🤖 Generated with Claude Code

… parameter may be null

The `post_password_required` and `the_password_form` filters are applied after `get_post()` without a null check, so they receive null when no post is found (e.g. calling `post_password_required()` outside the loop). `post_password_required()` even reaches the filter on its first branch because `empty( $post->post_password )` is true for null. The `media_view_settings` and `media_view_strings` filters receive null whenever `wp_enqueue_media()` is called without a `post` arg, such as on the Media Library screen, since `$post` is explicitly initialized to null there. Callbacks that type-hint `WP_Post` for these parameters fatal with a `TypeError` in those cases. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Use "or null if no post is found", as already used by the `get_the_modified_date`, `get_the_modified_time`, `post_password_required`, and `the_password_form` filters. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

`WP_REST_Posts_Controller::check_password_required()` is hooked to `post_password_required`, which can now be documented as passing null, and the method already handles that case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The Twenty Sixteen, Twenty Seventeen, and Twenty Twenty-One callbacks for `wp_get_attachment_image_attributes` copied the hook's `WP_Post` docs. Update them to match the hook now that it documents a null `$attachment`. None of the callbacks dereference it unguarded, so this is docs only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

`WP_Abilities_Content::allow_password_content()` said the core filter always passes a `WP_Post`, which contradicts the hook docs now that they allow null. Its guard already handles null. Also fix the grammar in `WP_REST_Posts_Controller::check_password_required()`: "The post been password checked" becomes "The post being password checked". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

`twenty_twenty_one_password_form()` is hooked to `the_password_form`, which passes null when no post is found. The function already handles that, since it runs `$post` through `get_post()` and checks `empty( $post->ID )`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Document `$required` as `bool` and `$post` as `WP_Post|null`, matching the `post_password_required` filter instead of `mixed`. No native type hints are added, since an earlier callback returning a non-bool would then cause a fatal error. The existing `(bool)` cast and `instanceof WP_Post` check still guard at runtime. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-30T18:04:31Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

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.

Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

@propsbot add <username> to give props to a GitHub user. Requires write access.
@propsbot remove <username> to leave a user out of the props. Requires write access.
@propsbot refresh to refresh this list. Adding the props-bot label works too.

github-actions · 2026-10-30T18:08:37Z

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.

Several hooks document their post parameter as `WP_Post` even though `get_post()` can return null before the hook fires, so callbacks that type-hint `WP_Post` fatal with a `TypeError`. This was reported for the Image Placeholders plugin, where a plugin filtered `post_thumbnail_id` to an ID with no post, leading `wp_get_attachment_image()` to pass a null `$attachment` to `wp_get_attachment_image_attributes`. The same applies to `post_password_required` and `the_password_form` when no post is found, and to `media_view_settings` and `media_view_strings` whenever `wp_enqueue_media()` is not called for a specific post. Core and bundled theme callbacks of these hooks are updated to match. Developed in #15257. See #65860. git-svn-id: https://develop.svn.wordpress.org/trunk@65075 602fd350-edb4-49c9-b593-d223f7449a82

Several hooks document their post parameter as `WP_Post` even though `get_post()` can return null before the hook fires, so callbacks that type-hint `WP_Post` fatal with a `TypeError`. This was reported for the Image Placeholders plugin, where a plugin filtered `post_thumbnail_id` to an ID with no post, leading `wp_get_attachment_image()` to pass a null `$attachment` to `wp_get_attachment_image_attributes`. The same applies to `post_password_required` and `the_password_form` when no post is found, and to `media_view_settings` and `media_view_strings` whenever `wp_enqueue_media()` is not called for a specific post. Core and bundled theme callbacks of these hooks are updated to match. Developed in WordPress/wordpress-develop#15257. See #65860. Built from https://develop.svn.wordpress.org/trunk@65075 git-svn-id: http://core.svn.wordpress.org/trunk@64225 1a063a9b-81f0-0310-95a4-ce76da25c4cd

westonruter and others added 8 commits October 30, 2026 10:19

Document that wp_get_attachment_image_attributes's $attachment filter…

8051b5c

… parameter may be null

Reword null $attachment description to match existing hook docs

5e11b9c

Use "or null if no post is found", as already used by the `get_the_modified_date`, `get_the_modified_time`, `post_password_required`, and `the_password_form` filters. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

westonruter marked this pull request as ready for review October 30, 2026 18:04

westonruter mentioned this pull request Oct 30, 2026

Image Placeholders: TypeError in dominant_color_update_attachment_image_attributes() when the attachment is null WordPress/performance#2742

Closed

westonruter closed this Oct 30, 2026

westonruter mentioned this pull request Oct 30, 2026

Fix fatal error when image attachment post is null WordPress/performance#2743

Merged

Navigation Menu

Repository navigation

Docs: Document hooks that may pass a null post object - #15257

Docs: Document hooks that may pass a null post object#15257
westonruter wants to merge 8 commits into
WordPress:trunkfrom
westonruter:fix/wp-get-attachment-image-attributes-filter-docs

westonruter commented Oct 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 30, 2026

Uh oh!

github-actions Bot commented Oct 30, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

westonruter commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Use of AI Tools

Uh oh!

github-actions Bot commented Oct 30, 2026

Uh oh!

github-actions Bot commented Oct 30, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

westonruter commented Oct 30, 2026 •

edited

Loading