Build/Test Tools: Teach PHPStan WordPress hash notation

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

@@ -84,13 +84,24 @@ 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.
       - 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-result-cache-${{ hashFiles('phpstan.neon.dist', 'tests/phpstan/*.neon', 'tests/phpstan/*.php') }}-${{ github.run_id }}"
           restore-keys: |
-            phpstan-result-cache-
+            phpstan-result-cache-${{ hashFiles('phpstan.neon.dist', 'tests/phpstan/*.neon', 'tests/phpstan/*.php') }}-
 
       - name: Run PHP static analysis tests
         id: phpstan
@@ -193,7 +204,7 @@ jobs:
         if: ${{ !cancelled() }}
         with:
           path: .cache
-          key: "phpstan-result-cache-${{ github.run_id }}"
+          key: "phpstan-result-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[]  $0 Post mime types.
+ *     @type string[] $1 Available post mime types.
  * }
  */
 function wp_edit_attachments_query( $q = false ) {

src/wp-includes/class-wp-http.php

@@ -153,17 +153,18 @@ class WP_Http {
 	 * @return array|WP_Error {
 	 *     Array of response data, or a WP_Error instance upon error.
 	 *
-	 *     @type \WpOrg\Requests\Utility\CaseInsensitiveDictionary $headers       Response headers keyed by name.
-	 *     @type string                                            $body          Response body.
-	 *     @type array                                             $response      {
+	 *     @type \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array $headers       Response headers keyed by name.
+	 *                                                                                  An empty array for a non-blocking request.
+	 *     @type string                                                 $body          Response body.
+	 *     @type array                                                  $response      {
 	 *         Array of HTTP response data.
 	 *
 	 *         @type int|false    $code    HTTP response status code.
 	 *         @type string|false $message HTTP response message.
 	 *     }
-	 *     @type WP_Http_Cookie[]                                  $cookies       Array of cookies set by the server.
-	 *     @type string|null                                       $filename      Optional. Filename of the response.
-	 *     @type WP_HTTP_Requests_Response|null                    $http_response Response object.
+	 *     @type WP_Http_Cookie[]                                       $cookies       Array of cookies set by the server.
+	 *     @type string|null                                            $filename      Optional. Filename of the response.
+	 *     @type WP_HTTP_Requests_Response|null                         $http_response Response object.
 	 * }
 	 */
 	public function request( $url, $args = array() ) {
@@ -715,7 +716,7 @@ public static function processResponse( $response ) { // phpcs:ignore WordPress.
 	 *         @type int    $code    The response status code. Default 0.
 	 *         @type string $message The response message. Default empty.
 	 *     }
-	 *     @type array            $newheaders The processed header data as a multidimensional array.
+	 *     @type array            $headers    The processed header data as a multidimensional array.
 	 *     @type WP_Http_Cookie[] $cookies    If the original headers contain the 'Set-Cookie' key,
 	 *                                        an array containing `WP_Http_Cookie` objects is returned.
 	 * }

src/wp-includes/class-wp-xmlrpc-server.php

@@ -3190,7 +3190,7 @@ public function wp_deletePage( $args ) {
 	 *     @type int    $1 Page ID.
 	 *     @type string $2 Username.
 	 *     @type string $3 Password.
-	 *     @type string $4 Content.
+	 *     @type array  $4 Content struct.
 	 *     @type int    $5 Publish flag. 0 for draft, 1 for publish.
 	 * }
 	 * @return array|IXR_Error

src/wp-includes/class-wpdb.php

@@ -2065,7 +2065,7 @@ public function db_connect( $allow_bail = true ) {
 	 *     False if the host couldn't be parsed.
 	 *
 	 *     @type string      $0 Host name.
-	 *     @type string|null $1 Port.
+	 *     @type int|null    $1 Port.
 	 *     @type string|null $2 Socket.
 	 *     @type bool        $3 Whether it is an IPv6 address.
 	 * }

src/wp-includes/cron.php

@@ -765,7 +765,7 @@ function wp_unschedule_hook( $hook, $wp_error = false ) {
  *                            Default empty array.
  * @param int|null $timestamp Optional. Unix timestamp (UTC) of the event. If not specified, the next scheduled event
  *                            is returned. Default null.
- * @return object|false {
+ * @return stdClass|false {
  *     The event object. False if the event does not exist.
  *
  *     @type string       $hook      Action hook to execute when the event is run.

src/wp-includes/fonts.php

@@ -142,6 +142,14 @@ function wp_get_font_dir() {
  *     @type string       $baseurl URL path without subdir.
  *     @type string|false $error   False or error message.
  * }
+ * @phpstan-return array{
+ *                     path: non-empty-string,
+ *                     url: non-empty-string,
+ *                     subdir: non-empty-string,
+ *                     basedir: non-empty-string,
+ *                     baseurl: non-empty-string,
+ *                 }
+ *                |array{ error: non-empty-string }
  */
 function wp_font_dir( $create_dir = true ) {
 	/*

src/wp-includes/functions.php

@@ -2915,9 +2915,9 @@ function _wp_check_existing_file_names( $filename, $files ) {
  * @return array {
  *     Information about the newly-uploaded file.
  *
- *     @type string       $file  Filename of the newly-uploaded file.
- *     @type string       $url   URL of the uploaded file.
- *     @type string       $type  File type.
+ *     @type string       $file  Optional. Filename of the newly-uploaded file. Not set if there has been an error.
+ *     @type string       $url   Optional. URL of the uploaded file. Not set if there has been an error.
+ *     @type string       $type  Optional. File type. Not set if there has been an error.
  *     @type string|false $error Error message, if there has been an error.
  * }
  */

src/wp-includes/link-template.php

@@ -4411,6 +4411,7 @@ function is_avatar_comment_type( $comment_type ) {
  *                                      false or not set if none was found.
  *     @type string|false $url          The URL of the avatar that was found, or false.
  * }
+ * @phpstan-return array{ found_avatar: bool, url: string|false, ... }
  */
 function get_avatar_data( $id_or_email, $args = null ) {
 	$args = wp_parse_args(

src/wp-includes/post.php

@@ -2011,7 +2011,7 @@ function unregister_post_type( $post_type ) {
  * @see map_meta_cap()
  *
  * @param object $args Post type registration arguments.
- * @return object {
+ * @return stdClass {
  *     Object with all the capabilities as member variables.
  *
  *     @type string $edit_post              Capability to edit a post.

src/wp-includes/taxonomy.php

@@ -648,7 +648,7 @@ function unregister_taxonomy( $taxonomy ) {
  * @since 6.6.0 Added the `template_name` label.
  *
  * @param WP_Taxonomy $tax Taxonomy object.
- * @return object {
+ * @return stdClass {
  *     Taxonomy labels object. The first default value is for non-hierarchical taxonomies
  *     (like tags) and the second one is for hierarchical taxonomies (like categories).
  *