Skip to content

Follow up on review feedback for the dual-mode void conditional return types #13371

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
westonruter wants to merge 5 commits into
base: trunk
Choose a base branch
from
Open

Follow up on review feedback for the dual-mode void conditional return types #13371

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
eaddbe4
Cover every falsy `$args` scalar in the undecidable branch
westonruter Sep 2, 2026
32d8d7c
Correct the `wp_dropdown_languages()` bail description
westonruter Sep 2, 2026
7dd8325
Say what `the_date()` and `the_modified_date()` return
westonruter Sep 2, 2026
20c7f9d
Restore `void` on two `wpdb` methods that never return a value
westonruter Sep 2, 2026
96a52a7
Name `null` in the tags whose retrieval branch can return it
westonruter Sep 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/wp-content/themes/twentytwenty/inc/template-tags.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,8 +107,8 @@ function twentytwenty_site_logo( $args = array(), $display = true ) {
* @since Twenty Twenty 1.0
*
* @param bool $display Display or return the HTML.
* @return string|void The HTML when `$display` is false, null when the site has no
* description. Nothing otherwise.
* @return string|null|void The HTML when `$display` is false, null when the site has no
* description. Nothing otherwise.
* @phpstan-return ( $display is true ? void : string|null )
*/
function twentytwenty_site_description( $display = true ) {
Expand Down
2 changes: 1 addition & 1 deletion src/wp-includes/author-template.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -453,7 +453,7 @@ function get_author_posts_url( $author_id, $author_nicename = '' ) {
* @phpstan-return (
* $args is array{ echo: false|0|''|'0', ... }
* ? string
* : ( $args is ''|array ? void : string|null )
* : ( $args is ''|'0'|array ? void : string|null )
* )
*/
function wp_list_authors( $args = '' ) {
Expand Down
2 changes: 1 addition & 1 deletion src/wp-includes/bookmark-template.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,7 @@ function _walk_bookmarks( $bookmarks, $args = '' ) {
* @phpstan-return (
* $args is array{ echo: false|0|''|'0', ... }
* ? string
* : ( $args is ''|array ? void : string|null )
* : ( $args is ''|'0'|array ? void : string|null )
* )
*/
function wp_list_bookmarks( $args = '' ) {
Expand Down
8 changes: 4 additions & 4 deletions src/wp-includes/category-template.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -710,15 +710,15 @@ function wp_list_categories( $args = '' ) {
* associated with the taxonomy.
* @type bool $echo Whether or not to echo the return value. Default true.
* }
* @return string|string[]|void Tag cloud as a string, or as an array when the 'format' argument
* is 'array'. Null on failure. Nothing when 'echo' is true and
* 'format' is not 'array'.
* @return string|string[]|null|void Tag cloud as a string, or as an array when the 'format'
* argument is 'array'. Null on failure. Nothing when 'echo' is
* true and 'format' is not 'array'.
* @phpstan-return (
* $args is array{ format: 'array', ... }
* ? string[]|null
* : ( $args is array{ echo: false|0|''|'0', ... }
* ? string|null
* : ( $args is ''|array ? void : string|string[]|null ) )
* : ( $args is ''|'0'|array ? void : string|string[]|null ) )
* )
*/
function wp_tag_cloud( $args = '' ) {
Expand Down
8 changes: 2 additions & 6 deletions src/wp-includes/class-wpdb.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1794,7 +1794,7 @@ public function esc_like( $text ) {
* @global array $EZSQL_ERROR Stores error information of query and error string.
*
* @param string $str The error to display.
* @return null|false Null if the showing of errors is enabled, false if disabled.
* @return void|false Void if the showing of errors is enabled, false if disabled.
*/
public function print_error( $str = '' ) {
global $EZSQL_ERROR;
Expand Down Expand Up @@ -1855,8 +1855,6 @@ public function print_error( $str = '' ) {
$query
);
}

return null;
}

/**
Expand Down Expand Up @@ -4068,7 +4066,7 @@ public function close() {
* @since 2.5.0
*
* @global string $required_mysql_version The minimum required MySQL version string.
* @return WP_Error|null
* @return void|WP_Error Void if the server meets the minimum version, WP_Error if not.
*/
public function check_database_version() {
global $required_mysql_version;
Expand All @@ -4079,8 +4077,6 @@ public function check_database_version() {
/* translators: 1: WordPress version number, 2: Minimum required MySQL version number. */
return new WP_Error( 'database_version', sprintf( __( '<strong>Error:</strong> WordPress %1$s requires MySQL %2$s or higher' ), $wp_version, $required_mysql_version ) );
}

return null;
}

/**
Expand Down
6 changes: 3 additions & 3 deletions src/wp-includes/comment-template.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2233,12 +2233,12 @@ function _get_comment_reply_id( $post = null ) {
* @type bool $echo Whether to echo the output or return it. Default true.
* }
* @param WP_Comment[] $comments Optional. Array of WP_Comment objects. Default null.
* @return string|void HTML list of comments when 'echo' is false, null when there are no
* comments to list. Nothing otherwise.
* @return string|null|void HTML list of comments when 'echo' is false, null when there are
* no comments to list. Nothing otherwise.
* @phpstan-return (
* $args is array{ echo: false|0|''|'0', ... }
* ? string|null
* : ( $args is ''|array ? void : string|null )
* : ( $args is ''|'0'|array ? void : string|null )
* )
*/
function wp_list_comments( $args = array(), $comments = null ) {
Expand Down
4 changes: 2 additions & 2 deletions src/wp-includes/functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8737,8 +8737,8 @@ function wp_get_default_update_php_url() {
* @param string $before Markup to output before the annotation. Default `<p class="description">`.
* @param string $after Markup to output after the annotation. Default `</p>`.
* @param bool $display Whether to echo or return the markup. Default `true` for echo.
* @return string|void Update PHP page annotation when `$display` is false, null when no
* annotation is available. Nothing otherwise.
* @return string|null|void Update PHP page annotation when `$display` is false, null when
* no annotation is available. Nothing otherwise.
* @phpstan-return ( $display is true ? void : string|null )
*/
function wp_update_php_annotation( $before = '<p class="description">', $after = '</p>', $display = true ) {
Expand Down
35 changes: 18 additions & 17 deletions src/wp-includes/general-template.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1705,8 +1705,8 @@ function wp_title( $sep = '&raquo;', $display = true, $seplocation = '' ) {
*
* @param string $prefix Optional. What to display before the title.
* @param bool $display Optional. Whether to display or retrieve title. Default true.
* @return string|void Title when retrieving, null on failure.
* Nothing when displaying.
* @return string|null|void Title when retrieving, null on failure.
* Nothing when displaying.
* @phpstan-return ( $display is true ? void : string|null )
*/
function single_post_title( $prefix = '', $display = true ) {
Expand Down Expand Up @@ -1743,8 +1743,8 @@ function single_post_title( $prefix = '', $display = true ) {
*
* @param string $prefix Optional. What to display before the title.
* @param bool $display Optional. Whether to display or retrieve title. Default true.
* @return string|void Title when retrieving, null on failure.
* Nothing when displaying.
* @return string|null|void Title when retrieving, null on failure.
* Nothing when displaying.
* @phpstan-return ( $display is true ? void : string|null )
*/
function post_type_archive_title( $prefix = '', $display = true ) {
Expand Down Expand Up @@ -1787,8 +1787,8 @@ function post_type_archive_title( $prefix = '', $display = true ) {
*
* @param string $prefix Optional. What to display before the title.
* @param bool $display Optional. Whether to display or retrieve title. Default true.
* @return string|void Title when retrieving, null on failure.
* Nothing when displaying.
* @return string|null|void Title when retrieving, null on failure.
* Nothing when displaying.
* @phpstan-return ( $display is true ? void : string|null )
*/
function single_cat_title( $prefix = '', $display = true ) {
Expand All @@ -1810,8 +1810,8 @@ function single_cat_title( $prefix = '', $display = true ) {
*
* @param string $prefix Optional. What to display before the title.
* @param bool $display Optional. Whether to display or retrieve title. Default true.
* @return string|void Title when retrieving, null on failure.
* Nothing when displaying.
* @return string|null|void Title when retrieving, null on failure.
* Nothing when displaying.
* @phpstan-return ( $display is true ? void : string|null )
*/
function single_tag_title( $prefix = '', $display = true ) {
Expand All @@ -1833,8 +1833,8 @@ function single_tag_title( $prefix = '', $display = true ) {
*
* @param string $prefix Optional. What to display before the title.
* @param bool $display Optional. Whether to display or retrieve title. Default true.
* @return string|void Title when retrieving, null on failure.
* Nothing when displaying.
* @return string|null|void Title when retrieving, null on failure.
* Nothing when displaying.
* @phpstan-return ( $display is true ? void : string|null )
*/
function single_term_title( $prefix = '', $display = true ) {
Expand Down Expand Up @@ -2235,12 +2235,12 @@ function get_archives_link( $url, $text, $format = 'html', $before = '', $after
* @type string $day Day. Default current day.
* @type string $w Week. Default current week.
* }
* @return string|void Archive links when 'echo' is false, null when the post type is
* not viewable. Nothing otherwise.
* @return string|null|void Archive links when 'echo' is false, null when the post type is
* not viewable. Nothing otherwise.
* @phpstan-return (
* $args is array{ echo: false|0|''|'0', ... }
* ? string|null
* : ( $args is ''|array ? void : string|null )
* : ( $args is ''|'0'|array ? void : string|null )
* )
*/
function wp_get_archives( $args = '' ) {
Expand Down Expand Up @@ -2511,8 +2511,8 @@ function calendar_week_mod( $num ) {
* @type bool $display Whether to display the calendar output. Default true.
* @type string $post_type Optional. Post type. Default 'post'.
* }
* @return string|void Calendar HTML when `$display` is false, null when the site has
* no posts. Nothing otherwise.
* @return string|null|void Calendar HTML when `$display` is false, null when the site has
* no posts. Nothing otherwise.
* @phpstan-return ( $args is array{ display: false|0|''|'0', ... } ? string|null : void )
*/
function get_calendar( $args = array() ) {
Expand Down Expand Up @@ -2927,7 +2927,8 @@ function the_date_xml() {
* @param string $before Optional. Output before the date. Default empty.
* @param string $after Optional. Output after the date. Default empty.
* @param bool $display Optional. Whether to echo the date or return it. Default true.
* @return string|void String if retrieving.
* @return string|void The date when `$display` is false, or an empty string when the post's
* date matches the previously output one. Nothing otherwise.
* @phpstan-return ( $display is true ? void : string )
*/
function the_date( $format = '', $before = '', $after = '', $display = true ) {
Expand Down Expand Up @@ -3003,7 +3004,7 @@ function get_the_date( $format = '', $post = null ) {
* @param string $before Optional. Output before the date. Default empty.
* @param string $after Optional. Output after the date. Default empty.
* @param bool $display Optional. Whether to echo the date or return it. Default true.
* @return string|void String if retrieving.
* @return string|void The modified date when `$display` is false, nothing otherwise.
* @phpstan-return ( $display is true ? void : string )
*/
function the_modified_date( $format = '', $before = '', $after = '', $display = true ) {
Expand Down
9 changes: 7 additions & 2 deletions src/wp-includes/l10n.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1736,8 +1736,13 @@ function wp_get_l10n_php_file_data( $php_file ) {
* instead of an empty value. Default false.
* }
* @return string|void HTML dropdown list of languages. Always returned, whether or not
* 'echo' is true; nothing is returned when the required `id` or `name`
* argument is missing.
* 'echo' is true; nothing is returned when the 'id' or 'name'
* argument is empty.
* @phpstan-return (
* $args is array{ id: ''|'0', ... }

@IanDelMar IanDelMar Sep 3, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better use false|0|0.0|''|'0'|[]|null. While the docs say that $args['id'] and $args['name'] should be string, other values may still be passed. In those cases, PHPStan may incorrectly infer a string return type.

This may apply to other conditional return types as well.

* ? void
* : ( $args is array{ name: ''|'0', ... } ? void : string )
* )
*/
function wp_dropdown_languages( $args = array() ) {

Expand Down
14 changes: 7 additions & 7 deletions src/wp-includes/link-template.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1131,8 +1131,8 @@ function get_edit_term_link( $term, $taxonomy = '', $object_type = '' ) {
* @param string $after Optional. Display after edit link. Default empty.
* @param int|WP_Term|null $term Optional. Term ID or object. If null, the queried object will be inspected. Default null.
* @param bool $display Optional. Whether or not to echo the return. Default true.
* @return string|void HTML content when retrieving, null on failure or without the
* capability to edit the term. Nothing when displaying.
* @return string|null|void HTML content when retrieving, null on failure or without the
* capability to edit the term. Nothing when displaying.
* @phpstan-return ( $display is true ? void : string|null )
*/
function edit_term_link( $link = '', $before = '', $after = '', $term = null, $display = true ) {
Expand Down Expand Up @@ -3268,16 +3268,16 @@ function previous_comments_link( $label = '' ) {
* @global WP_Rewrite $wp_rewrite WordPress rewrite component.
*
* @param string|array $args Optional args. See paginate_links(). Default empty array.
* @return string|string[]|void Markup for comment page links, or an array of them when the 'type'
* argument is 'array'. Null if the query is not for an existing single
* post of any post type. Nothing when 'echo' is true and 'type' is not
* 'array'.
* @return string|string[]|null|void Markup for comment page links, or an array of them when
* the 'type' argument is 'array'. Null if the query is not for
* an existing single post of any post type. Nothing when 'echo'
* is true and 'type' is not 'array'.
* @phpstan-return (
* $args is array{ type: 'array', ... }
* ? string[]|null
* : ( $args is array{ echo: false|0|''|'0', ... }
* ? string|null
* : ( $args is ''|array ? void : string|string[]|null ) )
* : ( $args is ''|'0'|array ? void : string|string[]|null ) )
* )
*/
function paginate_comments_links( $args = array() ) {
Expand Down
14 changes: 7 additions & 7 deletions src/wp-includes/post-template.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ function get_the_ID() { // phpcs:ignore WordPress.NamingConventions.ValidFunctio
* @param string $before Optional. Markup to prepend to the title. Default empty.
* @param string $after Optional. Markup to append to the title. Default empty.
* @param bool $display Optional. Whether to echo or return the title. Default true for echo.
* @return string|void Current post title when `$display` is false, null when the title
* is empty. Nothing otherwise.
* @return string|null|void Current post title when `$display` is false, null when the
* title is empty. Nothing otherwise.
* @phpstan-return ( $display is true ? void : string|null )
*/
function the_title( $before = '', $after = '', $display = true ) {
Expand Down Expand Up @@ -77,12 +77,12 @@ function the_title( $before = '', $after = '', $display = true ) {
* @type bool $echo Whether to echo or return the title. Default true for echo.
* @type WP_Post $post Current post object to retrieve the title for.
* }
* @return string|void The title attribute when 'echo' is false, null when the title is
* empty. Nothing otherwise.
* @return string|null|void The title attribute when 'echo' is false, null when the title
* is empty. Nothing otherwise.
* @phpstan-return (
* $args is array{ echo: false|0|''|'0', ... }
* ? string|null
* : ( $args is ''|array ? void : string|null )
* : ( $args is ''|'0'|array ? void : string|null )
* )
*/
function the_title_attribute( $args = '' ) {
Expand Down Expand Up @@ -1309,7 +1309,7 @@ function wp_dropdown_pages( $args = '' ) {
* @phpstan-return (
* $args is array{ echo: false|0|''|'0', ... }
* ? string
* : ( $args is ''|array ? void : string|null )
* : ( $args is ''|'0'|array ? void : string|null )
* )
*/
function wp_list_pages( $args = '' ) {
Expand Down Expand Up @@ -1437,7 +1437,7 @@ function wp_list_pages( $args = '' ) {
* @phpstan-return (
* $args is array{ echo: false|0|''|'0', ... }
* ? string
* : ( $args is ''|array ? void : string|null )
* : ( $args is ''|'0'|array ? void : string|null )
* )
*/
function wp_page_menu( $args = array() ) {
Expand Down
2 changes: 1 addition & 1 deletion src/wp-includes/user.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -911,7 +911,7 @@ function get_users( $args = array() ) {
* @phpstan-return (
* $args is array{ echo: false|0|''|'0', ... }
* ? string
* : ( $args is ''|array ? void : string|null )
* : ( $args is ''|'0'|array ? void : string|null )
* )
*/
function wp_list_users( $args = array() ) {
Expand Down
Loading