Changeset 63941 for trunk/src/wp-includes/class-wp-theme.php

Timestamp:

09/26/2026 02:43:56 AM (6 weeks ago)

Author:

westonruter

Message:

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.

File:

• trunk/src/wp-includes/class-wp-theme.php (modified) (6 diffs)

trunk/src/wp-includes/class-wp-theme.php

@@ -6 +6 @@
  * @subpackage Theme
  * @since 3.4.0
+ *
+ * @phpstan-type Theme_Key 'Name'|'Version'|'Status'|'Title'|'Author'|'Author Name'|'Author URI'|'Description'|'Template'|'Stylesheet'|'Template Files'|'Stylesheet Files'|'Template Dir'|'Stylesheet Dir'|'Screenshot'|'Tags'|'Theme Root'|'Theme Root URI'|'Parent Theme'
  */
 #[AllowDynamicProperties]
@@ -655 +657 @@
          * @param mixed $offset
          * @return bool
+         *
+         * @phpstan-return ( $offset is Theme_Key ? true : false )
          */
         #[ReturnTypeWillChange]
@@ -697 +701 @@
          * @param mixed $offset
          * @return mixed
+         *
+         * @phpstan-return ( $offset is Theme_Key ? mixed : null )
          */
         #[ReturnTypeWillChange]
@@ -917 +923 @@
          * @return string|array|false Processed header. An array for Tags if `$markup` is false, string otherwise.
          *                            False on failure.
+         *
+         * @phpstan-return (
+         *     $markup is false
+         *         ? ( $header is 'Tags'
+         *             ? string[]|false
+         *             : string|false )
+         *         : string|false
+         * )
          */
         public function display( $header, $markup = true, $translate = true ) {
@@ -950 +964 @@
          *                       'UpdateURI'.
          * @param string $value  Value to sanitize.
-         * @return string|array An array for Tags header, string otherwise.
+         * @return string|string[] An array for Tags header, string otherwise.
+         *
+         * @phpstan-return ( $header is 'Tags' ? string[] : string )
          */
         private function sanitize_header( $header, $value ) {
@@ -1054 +1070 @@
          * @since 3.4.0
          *
-         * @param string       $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
-         * @param string|array $value  Value to translate. An array for Tags header, string otherwise.
-         * @return string|array Translated value. An array for Tags header, string otherwise.
+         * @param string          $header Theme header. Name, Description, Author, Version, ThemeURI, AuthorURI, Status, Tags.
+         * @param string|string[] $value  Value to translate. An array for Tags header, string otherwise.
+         * @return string|string[] Translated value. An array for Tags header, string otherwise.
+         *
+         * @phpstan-return ( $value is string ? string : string[] )
          */
         private function translate_header( $header, $value ) {