Build/Test Tools: Teach PHPStan WordPress hash notation

.github/workflows/reusable-phpstan-static-analysis-v1.yml

@@ -84,13 +84,30 @@ jobs:
       - name: Build WordPress
         run: npm run build:dev
 
+      # The directory holds more than the analysis results. PHPStan also stores what it read out of
+      # each source file there, the docblocks and signatures it found, keyed by that file's contents
+      # and nothing else. The extensions in `tests/phpstan` change what reading a file yields without
+      # changing the file: a parser node visitor rewrites a docblock in the syntax tree, and the bytes
+      # on disk stay as they were. A cache written before one of them changed therefore answers with
+      # what the old code saw, and the analysis silently runs against types no longer derived.
+      #
+      # Keying on the configuration and the extensions keeps a run from restoring a cache that
+      # predates either. The baselines are left out of the key: they only decide which reported errors
+      # are ignored, PHPStan invalidates the results cache on a configuration change by itself, and
+      # including them would discard the whole cache every time one is regenerated.
+      #
+      # The cache is renamed rather than only prefixed, because the key this replaces restored on
+      # `phpstan-result-cache-`, which every key below still begins with. A branch that has not
+      # merged this commit yet runs the workflow it has, and that workflow would prefix-match the
+      # caches written here: it would analyse without the extensions against reflection derived with
+      # them. A name of its own leaves those runs restoring only their own caches.
       - name: Cache PHP Static Analysis scan cache
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: .cache # This is defined in the base.neon file.
-          key: "phpstan-result-cache-${{ github.run_id }}"
+          key: "phpstan-analysis-cache-${{ hashFiles('phpstan.neon.dist', 'tests/phpstan/*.neon', 'tests/phpstan/*.php') }}-${{ github.run_id }}"
           restore-keys: |
-            phpstan-result-cache-
+            phpstan-analysis-cache-${{ hashFiles('phpstan.neon.dist', 'tests/phpstan/*.neon', 'tests/phpstan/*.php') }}-
 
       - name: Run PHP static analysis tests
         id: phpstan
@@ -193,7 +210,7 @@ jobs:
         if: ${{ !cancelled() }}
         with:
           path: .cache
-          key: "phpstan-result-cache-${{ github.run_id }}"
+          key: "phpstan-analysis-cache-${{ hashFiles('phpstan.neon.dist', 'tests/phpstan/*.neon', 'tests/phpstan/*.php') }}-${{ github.run_id }}"
 
       - name: Ensure version-controlled files are not modified or deleted
         run: git diff --exit-code

src/wp-admin/includes/class-wp-list-table.php

@@ -427,11 +427,15 @@ public function search_box( $text, $input_id ) {
 	 * @since 6.1.0
 	 *
 	 * @param array $link_data {
-	 *     An array of link data.
+	 *     An array of link data, keyed by view.
 	 *
-	 *     @type string $url     The link URL.
-	 *     @type string $label   The link label.
-	 *     @type bool   $current Optional. Whether this is the currently selected view.
+	 *     @type array ...$0 {
+	 *         Data for a single view link.
+	 *
+	 *         @type string $url     The link URL.
+	 *         @type string $label   The link label.
+	 *         @type bool   $current Optional. Whether this is the currently selected view.
+	 *     }
 	 * }
 	 * @return string[] An array of link markup. Keys match the `$link_data` input array.
 	 */

src/wp-admin/includes/misc.php

@@ -1570,12 +1570,14 @@ function _wp_privacy_settings_filter_draft_page_titles( $title, $page ) {
  * @return array|false {
  *     Array of PHP version data. False on failure.
  *
- *     @type string $recommended_version The PHP version recommended by WordPress.
- *     @type string $minimum_version     The minimum required PHP version.
- *     @type bool   $is_supported        Whether the PHP version is actively supported.
- *     @type bool   $is_secure           Whether the PHP version receives security updates.
- *     @type bool   $is_acceptable       Whether the PHP version is still acceptable or warnings
- *                                       should be shown and an update recommended.
+ *     @type string $recommended_version          The PHP version recommended by WordPress.
+ *     @type string $minimum_version              The minimum required PHP version.
+ *     @type bool   $is_supported                 Whether the PHP version is actively supported.
+ *     @type bool   $is_secure                    Whether the PHP version receives security updates.
+ *     @type bool   $is_acceptable                Whether the PHP version is still acceptable or warnings
+ *                                                should be shown and an update recommended.
+ *     @type bool   $is_lower_than_future_minimum Whether the PHP version is lower than the minimum PHP
+ *                                                version WordPress will require in a future release.
  * }
  */
 function wp_check_php_version() {

src/wp-admin/includes/post.php

@@ -1393,10 +1393,10 @@ function wp_edit_attachments_query_vars( $q = false ) {
  * @param array|false $q Optional. Array of query variables to use to build the query.
  *                       Defaults to the `$_GET` superglobal.
  * @return array {
- *     Array containing the post mime types and available post mime types.
+ *     Array containing the post mime types and the available post mime types, in that order.
  *
- *     @type array[]  $post_mime_types       Post mime types.
- *     @type string[] $avail_post_mime_types Available post mime types.
+ *     @type array<string, array{0: string, 1: string, 2: array}> $0 Post mime types. See get_post_mime_types().
+ *     @type string[]                                             $1 Available post mime types.
  * }
  */
 function wp_edit_attachments_query( $q = false ) {

src/wp-includes/class-wp-date-query.php

@@ -73,71 +73,69 @@ class WP_Date_Query {
 	 * @param array  $date_query {
 	 *     Array of date query clauses.
 	 *
-	 *     @type array ...$0 {
-	 *         @type string $column   Optional. The column to query against. If undefined, inherits the value of
-	 *                                the `$default_column` parameter. See WP_Date_Query::validate_column() and
-	 *                                the {@see 'date_query_valid_columns'} filter for the list of accepted values.
-	 *                                Default 'post_date'.
-	 *         @type string $compare  Optional. The comparison operator. Accepts '=', '!=', '>', '>=', '<', '<=',
-	 *                                'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. Default '='.
-	 *         @type string $relation Optional. The boolean relationship between the date queries. Accepts 'OR' or 'AND'.
-	 *                                Default 'OR'.
-	 *         @type array  ...$0 {
-	 *             Optional. An array of first-order clause parameters, or another fully-formed date query.
+	 *     @type string $column   Optional. The column to query against. If undefined, inherits the value of
+	 *                            the `$default_column` parameter. See WP_Date_Query::validate_column() and
+	 *                            the {@see 'date_query_valid_columns'} filter for the list of accepted values.
+	 *                            Default 'post_date'.
+	 *     @type string $compare  Optional. The comparison operator. Accepts '=', '!=', '>', '>=', '<', '<=',
+	 *                            'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. Default '='.
+	 *     @type string $relation Optional. The boolean relationship between the date queries. Accepts 'OR' or 'AND'.
+	 *                            Default 'OR'.
+	 *     @type array  ...$0 {
+	 *         Optional. An array of first-order clause parameters, or another fully-formed date query.
 	 *
-	 *             @type string|array $before {
-	 *                 Optional. Date to retrieve posts before. Accepts `strtotime()`-compatible string,
-	 *                 or array of 'year', 'month', 'day' values.
+	 *         @type string|array $before {
+	 *             Optional. Date to retrieve posts before. Accepts `strtotime()`-compatible string,
+	 *             or array of 'year', 'month', 'day' values.
 	 *
-	 *                 @type string $year  The four-digit year. Default empty. Accepts any four-digit year.
-	 *                 @type string $month Optional when passing array. The month of the year.
-	 *                                     Default (string:empty)|(array:1). Accepts numbers 1-12.
-	 *                 @type string $day   Optional when passing array. The day of the month.
-	 *                                     Default (string:empty)|(array:1). Accepts numbers 1-31.
-	 *             }
-	 *             @type string|array $after {
-	 *                 Optional. Date to retrieve posts after. Accepts `strtotime()`-compatible string,
-	 *                 or array of 'year', 'month', 'day' values.
+	 *             @type string $year  The four-digit year. Default empty. Accepts any four-digit year.
+	 *             @type string $month Optional when passing array. The month of the year.
+	 *                                 Default (string:empty)|(array:1). Accepts numbers 1-12.
+	 *             @type string $day   Optional when passing array. The day of the month.
+	 *                                 Default (string:empty)|(array:1). Accepts numbers 1-31.
+	 *         }
+	 *         @type string|array $after {
+	 *             Optional. Date to retrieve posts after. Accepts `strtotime()`-compatible string,
+	 *             or array of 'year', 'month', 'day' values.
 	 *
-	 *                 @type string $year  The four-digit year. Accepts any four-digit year. Default empty.
-	 *                 @type string $month Optional when passing array. The month of the year. Accepts numbers 1-12.
-	 *                                     Default (string:empty)|(array:12).
-	 *                 @type string $day   Optional when passing array. The day of the month. Accepts numbers 1-31.
-	 *                                     Default (string:empty)|(array:last day of month).
-	 *             }
-	 *             @type string       $column        Optional. Used to add a clause comparing a column other than
-	 *                                               the column specified in the top-level `$column` parameter.
-	 *                                               See WP_Date_Query::validate_column() and
-	 *                                               the {@see 'date_query_valid_columns'} filter for the list
-	 *                                               of accepted values. Default is the value of top-level `$column`.
-	 *             @type string       $compare       Optional. The comparison operator. Accepts '=', '!=', '>', '>=',
-	 *                                               '<', '<=', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. Comparisons
-	 *                                               support arrays in some time-related parameters. Default '='.
-	 *             @type bool         $inclusive     Optional. Include results from dates specified in 'before' or
-	 *                                               'after'. Default false.
-	 *             @type int|int[]    $year          Optional. The four-digit year number. Accepts any four-digit year
-	 *                                               or an array of years if `$compare` supports it. Default empty.
-	 *             @type int|int[]    $month         Optional. The two-digit month number. Accepts numbers 1-12 or an
-	 *                                               array of valid numbers if `$compare` supports it. Default empty.
-	 *             @type int|int[]    $week          Optional. The week number of the year. Accepts numbers 1-53 or an
-	 *                                               array of valid numbers if `$compare` supports it. Default empty.
-	 *             @type int|int[]    $dayofyear     Optional. The day number of the year. Accepts numbers 1-366 or an
-	 *                                               array of valid numbers if `$compare` supports it.
-	 *             @type int|int[]    $day           Optional. The day of the month. Accepts numbers 1-31 or an array
-	 *                                               of valid numbers if `$compare` supports it. Default empty.
-	 *             @type int|int[]    $dayofweek     Optional. The day number of the week. Accepts numbers 1-7 (1 is
-	 *                                               Sunday) or an array of valid numbers if `$compare` supports it.
-	 *                                               Default empty.
-	 *             @type int|int[]    $dayofweek_iso Optional. The day number of the week (ISO). Accepts numbers 1-7
-	 *                                               (1 is Monday) or an array of valid numbers if `$compare` supports it.
-	 *                                               Default empty.
-	 *             @type int|int[]    $hour          Optional. The hour of the day. Accepts numbers 0-23 or an array
-	 *                                               of valid numbers if `$compare` supports it. Default empty.
-	 *             @type int|int[]    $minute        Optional. The minute of the hour. Accepts numbers 0-59 or an array
-	 *                                               of valid numbers if `$compare` supports it. Default empty.
-	 *             @type int|int[]    $second        Optional. The second of the minute. Accepts numbers 0-59 or an
-	 *                                               array of valid numbers if `$compare` supports it. Default empty.
+	 *             @type string $year  The four-digit year. Accepts any four-digit year. Default empty.
+	 *             @type string $month Optional when passing array. The month of the year. Accepts numbers 1-12.
+	 *                                 Default (string:empty)|(array:12).
+	 *             @type string $day   Optional when passing array. The day of the month. Accepts numbers 1-31.
+	 *                                 Default (string:empty)|(array:last day of month).
 	 *         }
+	 *         @type string       $column        Optional. Used to add a clause comparing a column other than
+	 *                                           the column specified in the top-level `$column` parameter.
+	 *                                           See WP_Date_Query::validate_column() and
+	 *                                           the {@see 'date_query_valid_columns'} filter for the list
+	 *                                           of accepted values. Default is the value of top-level `$column`.
+	 *         @type string       $compare       Optional. The comparison operator. Accepts '=', '!=', '>', '>=',
+	 *                                           '<', '<=', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. Comparisons
+	 *                                           support arrays in some time-related parameters. Default '='.
+	 *         @type bool         $inclusive     Optional. Include results from dates specified in 'before' or
+	 *                                           'after'. Default false.
+	 *         @type int|int[]    $year          Optional. The four-digit year number. Accepts any four-digit year
+	 *                                           or an array of years if `$compare` supports it. Default empty.
+	 *         @type int|int[]    $month         Optional. The two-digit month number. Accepts numbers 1-12 or an
+	 *                                           array of valid numbers if `$compare` supports it. Default empty.
+	 *         @type int|int[]    $week          Optional. The week number of the year. Accepts numbers 1-53 or an
+	 *                                           array of valid numbers if `$compare` supports it. Default empty.
+	 *         @type int|int[]    $dayofyear     Optional. The day number of the year. Accepts numbers 1-366 or an
+	 *                                           array of valid numbers if `$compare` supports it.
+	 *         @type int|int[]    $day           Optional. The day of the month. Accepts numbers 1-31 or an array
+	 *                                           of valid numbers if `$compare` supports it. Default empty.
+	 *         @type int|int[]    $dayofweek     Optional. The day number of the week. Accepts numbers 1-7 (1 is
+	 *                                           Sunday) or an array of valid numbers if `$compare` supports it.
+	 *                                           Default empty.
+	 *         @type int|int[]    $dayofweek_iso Optional. The day number of the week (ISO). Accepts numbers 1-7
+	 *                                           (1 is Monday) or an array of valid numbers if `$compare` supports it.
+	 *                                           Default empty.
+	 *         @type int|int[]    $hour          Optional. The hour of the day. Accepts numbers 0-23 or an array
+	 *                                           of valid numbers if `$compare` supports it. Default empty.
+	 *         @type int|int[]    $minute        Optional. The minute of the hour. Accepts numbers 0-59 or an array
+	 *                                           of valid numbers if `$compare` supports it. Default empty.
+	 *         @type int|int[]    $second        Optional. The second of the minute. Accepts numbers 0-59 or an
+	 *                                           array of valid numbers if `$compare` supports it. Default empty.
 	 *     }
 	 * }
 	 * @param string $default_column Optional. Default column to query against. See WP_Date_Query::validate_column()