Make WordPress Core

Opened 4 months ago

Closed 4 months ago

#64645 closed enhancement (fixed)

Docs: Add missing null to $post parameter types in PHPDoc

Reported by: apermo's profile apermo Owned by: sergeybiryukov's profile SergeyBiryukov
Milestone: 7.0 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:

Description

Several functions across core accept null as a valid value for their $post parameter (defaulting to null in the function signature), but the corresponding @param type annotation does not include null.

This causes incorrect type information for IDEs, static analysis tools (PHPStan), and developer documentation.

Affected functions (all have $post = null in their signature):

  • get_the_date(), get_the_modified_date(), get_the_time(), get_post_time(), get_post_datetime(), get_the_modified_time(), get_post_modified_time(), get_post_timestamp() (general-template.php)
  • _get_comment_reply_id() (comment-template.php)
  • get_post_embed_url(), get_post_embed_html() (embed.php)
  • get_post_mime_type() (post.php)
  • get_the_excerpt(), post_class(), get_post_class(), get_page_template_slug() (post-template.php)
  • has_category(), has_tag(), has_term() (category-template.php)
  • _update_posts_count_on_transition_post_status() (ms-blogs.php)
  • display_media_state() (class-wp-widget-media.php)

Additionally, wp_force_plain_post_permalink() uses WP_Post|int|null instead of the conventional int|WP_Post|null ordering.

Change History (3)

This ticket was mentioned in PR #10938 on WordPress/wordpress-develop by @apermo.


4 months ago
#1

  • Keywords has-patch added

Several functions across core accept null as a valid value for their $post parameter ($post = null in the function signature), but the @param type annotation does not include null.

This patch adds null to the @param type for all affected functions across 9 files, and reorders wp_force_plain_post_permalink() from WP_Post|int|null to the conventional int|WP_Post|null.

## Changes

  • general-template.php: get_the_date, get_the_modified_date, get_the_time, get_post_time, get_post_datetime, get_the_modified_time, get_post_modified_time, get_post_timestamp
  • comment-template.php: _get_comment_reply_id
  • embed.php: get_post_embed_url, get_post_embed_html
  • post.php: get_post_mime_type
  • post-template.php: get_the_excerpt, post_class, get_post_class, get_page_template_slug
  • category-template.php: has_category, has_tag, has_term
  • ms-blogs.php: _update_posts_count_on_transition_post_status
  • class-wp-widget-media.php: display_media_state
  • link-template.php: wp_force_plain_post_permalink (type reorder)

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

## Use of AI Tools

Used Claude Code to identify all locations of the missing phpdoc and to help with summarizing the changes. Every change was monitored and reviewed by myself before opening the PR.

#2 @SergeyBiryukov
4 months ago

  • Milestone changed from Awaiting Review to 7.0

#3 @SergeyBiryukov
4 months ago

  • Owner set to SergeyBiryukov
  • Resolution set to fixed
  • Status changed from new to closed

In 61649:

Docs: Add missing null to $post parameter types in various functions.

Props apermo.
Fixes #64645.

Note: See TracTickets for help on using tickets.