Code Quality: Add conditional return types across core.
Declare PHPStan conditional return types on 86 functions and methods whose return type is selected by one of their arguments, in each case a selection their @return descriptions already spelled out in prose. They fall into these groups, alongside about thirty more of the same shape:
- An
$output argument choosing an object or an array form: get_term(), get_term_by(), get_category(), get_tag(), get_bookmark(), get_page_by_title() and others.
- The
count and fields arguments reshaping a query result: WP_Comment_Query::query(), get_sites(), get_networks(), get_users(), get_categories() and get_tags().
- A
'U' or 'G' date format returning a timestamp rather than a string: current_time(), mysql2date() and the get_the_date() family.
- A
$wp_error flag deciding how failure is reported: the cron scheduling functions, wp_set_comment_status(), wp_update_comment(), wp_insert_category() and wp_insert_link().
- A display flag returning markup instead of printing it:
single_month_title(), wp_list_categories(), wp_generate_tag_cloud() and paginate_links().
- The
WP_Theme header pipeline, from sanitize_header() through display().
- The
$callback and $priority arguments of has_filter(), has_action() and WP_Hook::has_filter() deciding between a bool and a priority.
With only the flat unions, a caller asking for an array was checked against a type that included an object, and the reverse. Likewise, a priority read back from has_filter() and passed on to remove_filter() was never narrowed to an integer.
Many of the annotations are adopted from the function map of the php-stubs/wordpress-stubs package, where they were developed and have long been relied on by plugin and theme authors. Each one was then checked against the body of the function it describes, and those claiming more than the code delivers were corrected. For instance:
- User IDs from
get_users() are typed as the numeric strings the query actually returns.
- A
null from paginate_links() is allowed when total is left to the main query, which may have only a single page.
- No conditional is declared for
wp_allow_comment(), since the pre_comment_approved filter has been allowed to return a WP_Error regardless of $wp_error as of r41980.
The @return descriptions of wp_allow_comment(), wp_set_comment_status(), wp_get_link_cats(), get_link() and the network query methods are corrected to match the code as well.
Two small code changes accompany the annotations. In wp_get_link_cats(), the WP_Error from wp_get_object_terms() is now returned rather than passed to array_unique(), and in wp_filter_oembed_result() the WP_Site::$blog_id numeric string is cast before being passed to switch_to_blog(), as the comparison on the line above already did.
The PHPStan baselines are regenerated, resolving eleven errors and adding five. Three of the additions are existing errors reworded by a narrower type. The other two record a pre-existing issue that the narrower get_post_time() type exposes, where the_weekday() and the_weekday_date() pass a value that may be false to WP_Locale::get_weekday().
Developed in https://github.com/WordPress/wordpress-develop/pull/13614.
Follow-up to r41980, r44154, r62680, r62822, r63358, r63441, r63488.
Props marian1, johnbillion, swissspidy, szepeviktor, mat-lipe, peter8nss, apermo, westonruter.
See #65817.
![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png){kind=logo}
