Make WordPress Core

Opened 8 months ago

Closed 8 months ago

#64645 closed enhancement (fixed)

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

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

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.


8 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
8 months ago

  • Milestone Awaiting Review → 7.0

#3 @SergeyBiryukov
8 months ago

  • Owner set to SergeyBiryukov
  • Resolution → fixed
  • Status new → 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.