WordPress.org

Make WordPress Core

Opened 4 months ago

Closed 5 weeks ago

#49832 closed defect (bug) (fixed)

Documented @return for get_post_thumbnail_id() is inaccurate

Reported by: theMikeD Owned by: SergeyBiryukov
Milestone: 5.5 Priority: normal
Severity: normal Version:
Component: Post Thumbnails Keywords: has-patch
Focuses: docs Cc:

Description

Ticket #40096 introduced a new change to the return value of get_post_thumbnail_id() to now always return an int rather than an empty string if the post is valid. The function documentation is now inaccurate because the @return statement was not updated correctly. In turn, this means the official API documentation is now also inaccurate.

It currently says

@return int|string Post thumbnail ID or empty string if the post does not exist.

It should read

@return int|string Post thumbnail ID if found, 0 if the thumbnail image is not set, or empty string if the post does not exist.

Change History (10)

#1 @theMikeD
4 months ago

  • Summary changed from Return value of to Documented @return for get_post_thumbnail_id() is inaccurate

#2 @SergeyBiryukov
4 months ago

  • Milestone changed from Awaiting Review to 5.5
  • Owner set to SergeyBiryukov
  • Status changed from new to reviewing

Thanks for the ticket!

Just noting that this currently depends on the outcome of #49751, there's a possibility that [47160] might be reverted.

#3 @dingo_d
4 months ago

If someone will be patching this, be sure to add the @since tag in the docs so that we know when the change was made :)

This ticket was mentioned in Slack in #docs by themiked. View the logs.


4 months ago

#5 @netpassprodsr
4 months ago

The outcome of #49751 as of 4/9/2020 is the following:

Milestone 5.4.1 deleted
Resolution set to invalid
Status changed from new to closed

which leaves the [47160] in limbo.
I agree with the logic that this code change attempts to address.
That said, until there's a formal endorsement that this code change will be remain in place, modifying the docs to fit a "volatile" code change is unwise at this point.
My recommendation is to resolve this as "maybelater" unless a more appropriate workflow/handling of these cases should be followed.

#6 @theMikeD
4 months ago

I don't think leaving the docs in a known bad state is the right answer here. If the underlying change gets reverted, then the doc can be reverted along with it. But waiting for a resolution is a recipe for it being knowingly wrong.

This ticket was mentioned in PR #233 on WordPress/wordpress-develop by netpassprod1.


4 months ago

get_post_thumbnail_id return value doc amendment

This correction to the php_doc brings the notes in line with the actual range of return values of the function.

Props theMikeD.
Fixes #49832.

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

<!--
Hi there! Thanks for contributing to WordPress!

Pull Requests in this GitHub repository must be linked to a ticket in the WordPress Core Trac instance (https://core.trac.wordpress.org), and are only used for code review. No pull requests will be merged on GitHub.

See the WordPress Handbook page on using PRs for Code Review more information: https://make.wordpress.org/core/handbook/contribute/git/github-pull-requests-for-code-review/

If this is your first time contributing, you may also find reviewing these guides first to be helpful:

-->

Trac ticket:

#8 @netpassprodsr
4 months ago

  • Keywords has-patch added

This ticket was mentioned in Slack in #core by netpassprodsr. View the logs.


4 months ago

#10 @SergeyBiryukov
5 weeks ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 48310:

Post Thumbnails: Change the return value of get_post_thumbnail_id() for a non-existing post to false instead of an empty string.

This further makes the function more consistent with get_the_ID() or wp_get_post_parent_id(), both returning false for a non-existing post.

Additionally, document that get_post_thumbnail_id() returns 0 if the thumbnail image is not set.

Follow-up to [47160].

Props theMikeD, dingo_d, netpassprodsr, SergeyBiryukov.
Fixes #49832. See #40096.

Note: See TracTickets for help on using tickets.