Tests / Build Scripts: Configure PHPStan levels 1-6 [Exploratory]

.github/workflows/php-static-analysis.yml

@@ -0,0 +1,100 @@
+name: PHPStan Static Analysis
+
+on:
+  # PHPStan testing was introduced in @todo.
+  push:
+    branches:
+      - trunk
+      - '6.9'
+      - '[7-9].[0-9]'
+    tags:
+      - '6.9'
+      - '6.9.[0-9]+'
+      - '[7-9].[0-9]'
+      - '[7-9]+.[0-9].[0-9]+'
+  pull_request:
+    branches:
+      - trunk
+      - '6.9'
+      - '[7-9].[0-9]'
+    paths:
+      # This workflow only scans PHP files.
+      - '**.php'
+      # These files configure Composer. Changes could affect the outcome.
+      - 'composer.*'
+      # These files configure PHPStan. Changes could affect the outcome.
+      - 'phpstan.neon.dist'
+      - 'tests/phpstan/base.neon'
+      # Confirm any changes to relevant workflow files.
+      - '.github/workflows/php-static-analysis.yml'
+      - '.github/workflows/reusable-php-static-analysis.yml'
+  workflow_dispatch:
+
+# Cancels all previous workflow runs for pull requests that have not completed.
+concurrency:
+  # The concurrency group contains the workflow name and the branch name for pull requests
+  # or the commit hash for any other events.
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.sha }}
+  cancel-in-progress: true
+
+# Disable permissions for all available scopes by default.
+# Any needed permissions should be configured at the job level.
+permissions: {}
+
+jobs:
+  # Runs PHPStan Static Analysis.
+  phpstan:
+    name: PHP coding standards
+    uses: ./.github/workflows/reusable-php-static-analysis.yml
+    permissions:
+      contents: read
+    if: ${{ github.repository == 'WordPress/wordpress-develop' || ( github.event_name == 'pull_request' && github.actor != 'dependabot[bot]' ) }}
+
+  slack-notifications:
+    name: Slack Notifications
+    uses: ./.github/workflows/slack-notifications.yml
+    permissions:
+      actions: read
+      contents: read
+    needs: [ phpstan ]
+    if: ${{ github.repository == 'WordPress/wordpress-develop' && github.event_name != 'pull_request' && always() }}
+    with:
+      calling_status: ${{ contains( needs.*.result, 'cancelled' ) && 'cancelled' || contains( needs.*.result, 'failure' ) && 'failure' || 'success' }}
+    secrets:
+      SLACK_GHA_SUCCESS_WEBHOOK: ${{ secrets.SLACK_GHA_SUCCESS_WEBHOOK }}
+      SLACK_GHA_CANCELLED_WEBHOOK: ${{ secrets.SLACK_GHA_CANCELLED_WEBHOOK }}
+      SLACK_GHA_FIXED_WEBHOOK: ${{ secrets.SLACK_GHA_FIXED_WEBHOOK }}
+      SLACK_GHA_FAILURE_WEBHOOK: ${{ secrets.SLACK_GHA_FAILURE_WEBHOOK }}
+
+  failed-workflow:
+    name: Failed workflow tasks
+    runs-on: ubuntu-24.04
+    permissions:
+      actions: write
+    needs: [ slack-notifications ]
+    if: |
+      always() &&
+      github.repository == 'WordPress/wordpress-develop' &&
+      github.event_name != 'pull_request' &&
+      github.run_attempt < 2 &&
+      (
+        contains( needs.*.result, 'cancelled' ) ||
+        contains( needs.*.result, 'failure' )
+      )
+
+    steps:
+      - name: Dispatch workflow run
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          retries: 2
+          retry-exempt-status-codes: 418
+          script: |
+            github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'failed-workflow.yml',
+              ref: 'trunk',
+              inputs: {
+                run_id: `${context.runId}`,
+              }
+            });

.github/workflows/reusable-php-static-analysis.yml

@@ -0,0 +1,95 @@
+##
+# A reusable workflow that runs PHP Static Analysis tests.
+##
+name: PHP Static Analysis
+
+on:
+  workflow_call:
+    inputs:
+      php-version:
+        description: 'The PHP version to use.'
+        required: false
+        type: 'string'
+        default: 'latest'
+
+# Disable permissions for all available scopes by default.
+# Any needed permissions should be configured at the job level.
+permissions: {}
+
+jobs:
+  # Runs PHP static analysis tests.
+  #
+  # Violations are reported inline with annotations.
+  #
+  # Performs the following steps:
+  # - Checks out the repository.
+  # - Sets up PHP.
+  # - Logs debug information.
+  # - Installs Composer dependencies.
+  # - Configures caching for PHP static analysis scans.
+  # - Make Composer packages available globally.
+  # - Runs PHPStan static analysis (with Pull Request annotations).
+  # - Saves the PHPStan result cache.
+  # - Ensures version-controlled files are not modified or deleted.
+  phpstan:
+    name: Run PHP static analysis
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          show-progress: ${{ runner.debug == '1' && 'true' || 'false' }}
+          persist-credentials: false
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@9e72090525849c5e82e596468b86eb55e9cc5401 # v2.32.0
+        with:
+          php-version: ${{ inputs.php-version }}
+          coverage: none
+          tools: cs2pr
+
+      - name: Log debug information
+        run: |
+          composer --version
+
+      # This date is used to ensure that the Composer cache is cleared at least once every week.
+      # http://man7.org/linux/man-pages/man1/date.1.html
+      - name: "Get last Monday's date"
+        id: get-date
+        run: echo "date=$(/bin/date -u --date='last Mon' "+%F")" >> "$GITHUB_OUTPUT"
+
+      # Since Composer dependencies are installed using `composer update` and no lock file is in version control,
+      # passing a custom cache suffix ensures that the cache is flushed at least once per week.
+      - name: Install Composer dependencies
+        uses: ramsey/composer-install@a2636af0004d1c0499ffca16ac0b4cc94df70565 # v3.1.0
+        with:
+          custom-cache-suffix: ${{ steps.get-date.outputs.date }}
+
+      - name: Make Composer packages available globally
+        run: echo "${PWD}/vendor/bin" >> "$GITHUB_PATH"
+
+      - name: Cache PHP Static Analysis scan cache
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
+        with:
+          path: .cache # This is defined in the base.neon file.
+          key: "phpstan-result-cache-${{ github.run_id }}"
+          restore-keys: |
+            phpstan-result-cache-
+
+      - name: Run PHP static analysis tests
+        id: phpstan
+        run: phpstan analyse -vvv --error-format=checkstyle | cs2pr
+
+      - name: "Save result cache"
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
+        if: ${{ !cancelled() }}
+        with:
+          path: .cache
+          key: "phpstan-result-cache-${{ github.run_id }}"
+
+      - name: Ensure version-controlled files are not modified or deleted
+        run: git diff --exit-code

.gitignore

@@ -22,6 +22,7 @@ wp-tests-config.php
 /build
 /tests/phpunit/build
 /wp-cli.local.yml
+/phpstan.neon
 /jsdoc
 /composer.lock
 /vendor

composer.json

@@ -23,6 +23,7 @@
 		"squizlabs/php_codesniffer": "3.13.2",
 		"wp-coding-standards/wpcs": "~3.2.0",
 		"phpcompatibility/phpcompatibility-wp": "~2.1.3",
+		"phpstan/phpstan": "~2.1.31",
 		"yoast/phpunit-polyfills": "^1.1.0"
 	},
 	"config": {
@@ -32,6 +33,7 @@
 		"lock": false
 	},
 	"scripts": {
+		"analyse": "@php ./vendor/bin/phpstan analyse --memory-limit=2G",
 		"compat": "@php ./vendor/squizlabs/php_codesniffer/bin/phpcs --standard=phpcompat.xml.dist --report=summary,source",
 		"format": "@php ./vendor/squizlabs/php_codesniffer/bin/phpcbf --report=summary,source",
 		"lint": "@php ./vendor/squizlabs/php_codesniffer/bin/phpcs --report=summary,source",

package.json

@@ -192,6 +192,7 @@
 		"env:logs": "node ./tools/local-env/scripts/docker.js logs",
 		"env:pull": "node ./tools/local-env/scripts/docker.js pull",
 		"test:performance": "wp-scripts test-playwright --config tests/performance/playwright.config.js",
+		"test:php:stan": "node ./tools/local-env/scripts/docker.js run --rm php ./vendor/bin/phpstan analyse --memory-limit=2G",
 		"test:php": "node ./tools/local-env/scripts/docker.js run --rm php ./vendor/bin/phpunit",
 		"test:coverage": "npm run test:php -- --coverage-html ./coverage/html/ --coverage-php ./coverage/php/report.php --coverage-text=./coverage/text/report.txt",
 		"test:e2e": "wp-scripts test-playwright --config tests/e2e/playwright.config.js",

phpcs.xml.dist

@@ -81,6 +81,9 @@
 	<exclude-pattern>/tests/phpunit/build*</exclude-pattern>
 	<exclude-pattern>/tests/phpunit/data/*</exclude-pattern>
 
+	<!-- PHPStan bootstrap, stubs, and baseline. -->
+	<exclude-pattern>/tests/phpstan/*</exclude-pattern>
+
 	<exclude-pattern>/tools/*</exclude-pattern>
 
 	<!-- Drop-in plugins. -->

phpstan.neon.dist

@@ -0,0 +1,55 @@
+# PHPStan configuration for WordPress Core.
+#
+# To overload this configuration, copy this file to phpstan.neon and adjust as needed.
+#
+# https://phpstan.org/config-reference
+
+includes:
+	# The WordPress Core configuration file includes the base configuration for the WordPress codebase.
+	- tests/phpstan/base.neon
+	# The baseline file includes preexisting errors in the codebase that should be ignored.
+	# https://phpstan.org/user-guide/baseline
+
+	- tests/phpstan/baseline.php # level 0.
+	- tests/phpstan/baseline/level-1.php
+	- tests/phpstan/baseline/level-2.php
+	- tests/phpstan/baseline/level-3.php
+	- tests/phpstan/baseline/level-4.php
+	- tests/phpstan/baseline/level-5.php
+	- tests/phpstan/baseline/level-6.php
+
+parameters:
+	level: 6
+	reportUnmatchedIgnoredErrors: true
+
+	ignoreErrors:
+		# Level 0:
+		- # Inner functions arent supported by PHPstan.
+			message: '#Function wxr_[a-z_]+ not found#'
+			path: src/wp-admin/includes/export.php
+		-
+			identifier: function.inner
+			path: src/wp-admin/includes/export.php
+			count: 13
+		-
+			identifier: function.inner
+			path: src/wp-admin/includes/file.php
+			count: 1
+		-
+			identifier: function.inner
+			path: src/wp-includes/canonical.php
+			count: 1
+
+		# Level 1:
+		- # These are too noisy at the moment.
+			message: '#Variable \$[a-zA-Z0-9_]+ might not be defined\.#'
+
+		# Level 2:
+		- # Callable-strings are used as callables in WordPress.
+			message: '#Default value of the parameter .* is incompatible with type callable.*#'
+
+		# Level 6:
+		- # WPCS syntax for iterable types is not supported.
+			identifier: missingType.iterableValue
+		- # Too noisy until `void` return types are allowed.
+			identifier: missingType.return

src/wp-admin/includes/class-wp-filesystem-ssh2.php

@@ -672,6 +672,7 @@ public function size( $file ) {
 	 *                      Default 0.
 	 */
 	public function touch( $file, $time = 0, $atime = 0 ) {
+		// @phpstan-ignore-next-line
 		// Not implemented.
 	}
 

src/wp-admin/press-this.php

@@ -22,8 +22,8 @@ function wp_load_press_this() {
 			403
 		);
 	} elseif ( is_plugin_active( $plugin_file ) ) {
-		include WP_PLUGIN_DIR . '/press-this/class-wp-press-this-plugin.php';
-		$wp_press_this = new WP_Press_This_Plugin();
+		include WP_PLUGIN_DIR . '/press-this/class-wp-press-this-plugin.php'; // @phpstan-ignore include.fileNotFound
+		$wp_press_this = new WP_Press_This_Plugin(); // @phpstan-ignore class.notFound
 		$wp_press_this->html();
 	} elseif ( current_user_can( 'activate_plugins' ) ) {
 		if ( file_exists( WP_PLUGIN_DIR . '/' . $plugin_file ) ) {

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

@@ -3365,7 +3365,7 @@ public function get_svg_filters( $origins ) {
 	 * @param array      $theme_json The theme.json like structure to inspect.
 	 * @param array      $path       Path to inspect.
 	 * @param bool|array $override   Data to compute whether to override the preset.
-	 * @return bool
+	 * @return bool|null True if the preset should override the defaults, false if not. Null if the override parameter is invalid.
 	 */
 	protected static function should_override_preset( $theme_json, $path, $override ) {
 		_deprecated_function( __METHOD__, '6.0.0', 'get_metadata_boolean' );
@@ -3400,6 +3400,8 @@ protected static function should_override_preset( $theme_json, $path, $override
 
 			return true;
 		}
+
+		return null;
 	}
 
 	/**

src/wp-includes/customize/class-wp-customize-background-image-setting.php

@@ -28,6 +28,7 @@ final class WP_Customize_Background_Image_Setting extends WP_Customize_Setting {
 	 * @since 3.4.0
 	 *
 	 * @param mixed $value The value to update. Not used.
+	 * @return bool|void Nothing is returned.
 	 */
 	public function update( $value ) {
 		remove_theme_mod( 'background_image_thumb' );

src/wp-includes/customize/class-wp-customize-filter-setting.php

@@ -24,6 +24,7 @@ class WP_Customize_Filter_Setting extends WP_Customize_Setting {
 	 * @since 3.4.0
 	 *
 	 * @param mixed $value The value to update.
+	 * @return bool|void Nothing is returned.
 	 */
 	public function update( $value ) {}
 }

src/wp-includes/customize/class-wp-customize-header-image-setting.php

@@ -32,6 +32,7 @@ final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting {
 	 * @global Custom_Image_Header $custom_image_header
 	 *
 	 * @param mixed $value The value to update.
+	 * @return bool|void Nothing is returned.
 	 */
 	public function update( $value ) {
 		global $custom_image_header;

src/wp-includes/media.php

@@ -4118,7 +4118,7 @@ function get_taxonomies_for_attachments( $output = 'names' ) {
  *              false otherwise.
  */
 function is_gd_image( $image ) {
-	if ( $image instanceof GdImage
+	if ( $image instanceof GdImage // @phpstan-ignore class.notFound (Only available with PHP8+.)
 		|| is_resource( $image ) && 'gd' === get_resource_type( $image )
 	) {
 		return true;

src/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php

@@ -56,6 +56,7 @@ public static function get_store( $store_name = 'default' ) {
 			return;
 		}
 		if ( ! isset( static::$stores[ $store_name ] ) ) {
+			// @phpstan-ignore new.static (In PHPStan 2.x we can enforce with `@phpstan-consistent-constructor`)
 			static::$stores[ $store_name ] = new static();
 			// Set the store name.
 			static::$stores[ $store_name ]->set_name( $store_name );

src/wp-includes/template.php

@@ -796,7 +796,7 @@ function load_template( $_template_file, $load_once = true, $args = array() ) {
 	}
 
 	if ( isset( $s ) ) {
-		$s = esc_attr( $s );
+		$s = esc_attr( $s ); // @phpstan-ignore variable.undefined (It's extracted from query vars.)
 	}
 
 	/**