Tests / Build Scripts: Configure PHPStan level 0

[justlevine]

Trac ticket: https://core.trac.wordpress.org/ticket/61175

This PR adds a PHPStan configuration for PHPStan level 0, along with tests and docs.

Based from #7619 - which remains in use to explore adopting future levels (alongside parallel remediation branches).

Proposal: https://make.wordpress.org/core/2025/07/11/proposal-phpstan-in-the-wordpress-core-development-workflow/

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props justlevine, westonruter, desrosj, johnbillion.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[Copilot]

Pull request overview

This PR introduces PHPStan level 0 static analysis configuration to WordPress Core, establishing a foundation for catching code errors without execution. The implementation includes PHPStan configuration files, bootstrap scripts, documentation, GitHub workflows for CI integration, and inline code annotations to suppress legitimate PHPStan warnings.

Changes:

• Added PHPStan level 0 configuration with baseline support for legacy code
• Added PHPStan annotations to source files to document legitimate suppressions
• Integrated PHPStan into CI/CD via GitHub workflows and npm/composer scripts

Reviewed changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
phpstan.neon.dist	Main PHPStan configuration with level 0 rules and baseline inclusion
tests/phpstan/base.neon	Base configuration defining paths, exclusions, and codebase-specific settings
tests/phpstan/baseline.php	Empty baseline file for future tech debt tracking
tests/phpstan/bootstrap.php	Defines WordPress constants for PHPStan discovery
tests/phpstan/README.md	Documentation for running and configuring PHPStan
src/wp-includes/template.php	Added PHPStan annotations and removed obsolete comment
src/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php	Added @phpstan-consistent-constructor annotation
src/wp-includes/media.php	Added annotation for PHP8+ GdImage class
src/wp-includes/functions.php	Added enhanced return type documentation for wp_die()
src/wp-includes/customize/*.php	Added @return documentation for overridden update() methods
src/wp-includes/class-wp-theme-json.php	Added null return value to match documented return type
src/wp-includes/class-wp-scripts.php	Removed obsolete PHPStan suppression comment
src/wp-admin/press-this.php	Added PHPStan annotations for plugin file includes
src/wp-admin/includes/class-wp-filesystem-ssh2.php	Added phpstan-ignore-next-line for unimplemented method
composer.json	Added phpstan/phpstan dependency and analyse script
package.json	Added test:php:stan npm script
phpcs.xml.dist	Excluded PHPStan files from coding standards checks
.gitignore	Added phpstan.neon to ignore list for local overrides
.github/workflows/php-static-analysis.yml	Main workflow for running PHPStan on pushes and PRs
.github/workflows/reusable-php-static-analysis.yml	Reusable workflow for PHPStan execution

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The version constraint "~2.1.33" is very specific and may cause issues. The tilde operator (~) for a three-part version like 2.1.33 means ">=2.1.33 <2.2.0". This constraint locks to a specific patch version which may not exist or may prevent receiving important bug fixes. Consider using "^2.1" (which means ">=2.1.0 <3.0.0") or "~2.1.0" (which means ">=2.1.0 <2.2.0") instead to allow flexibility for patch updates while staying within the same minor version

Suggested change

	"phpstan/phpstan": "~2.1.33",
	"phpstan/phpstan": "~2.1.0",

[justlevine]

@westonruter what are your thoughts on this one?

I definitely think we should pin at the version we commit, but I wouldn't want to Semver because contextually "nonbreaking enhancements" are breaking from an implementation POV if they create a new quality gate.

[westonruter]

That makes sense to me. So switching to ~2.1.0 would keep it at 2.1.x. This seems necessary because there is no composer.lock, which actually is curious since we package-lock.json. If we had a composer.lock then we'd be free to use ^2.1. But I suppose can't use it because of the different versions of PHP which may end up getting used when doing composer install.

So yeah, I guess go with ~2.1.0 and not ^2.1. When PHPStan 2.2 comes out, we'll have to manually upgrade.

[justlevine]

Depending on when we merge, there might be some value to pinning a minimum patch release too e.g. phpstan/phpstan#8438 (comment) . Leaving this for now, and might even bump it if this PR lingers. Keeping the issue open as a reminder to drop this as low as we think is worthwhile before we merge.

[johnbillion]

My preference is to pin to a specific version. Patch releases do introduce changes that affect the results (probably less so at level 0 but it definitely happens at higher levels).

[westonruter]

Done in 88d619b

[westonruter]

In Gruntfile.js, there is a precommit task, which includes precommit:php as well as format:php. Curiously, it doesn't to lint:php (probably because there are still so many violations), but it should run PHPStan since it can run on the entire codebase without errors.

Update: Done in 6a46b90.

[westonruter]

I tried running composer analyse and it seemed to finish but then it hung at 99%. Finally it errored:

[justlevine]

I tried running composer analyse and it seemed to finish but then it hung at 99%. Finally it errored:

@westonruter can you run it with -- --vvv? I believe that should show us which file it's timing out on.

(Also confirming that you're using the vanilla phpstan.neon.dist and the CLI is just inaccurate - if not, please share any modifications there too)

[westonruter]

Actually, I was using a local phpstan.neon which was overriding the one provided in this PR. When I try using the one in the PR, the result is actually worse. It never starts analyzing. This seems to be due to the paths config:

wordpress-develop/tests/phpstan/base.neon

Lines 62 to 63 in 75c8c54

	paths:
	- ../../src

If I change it to:

	paths:
		- ../../src/wp-admin
		- ../../src/wp-includes

Then it works, aside from two errors being found:

 ------ ---------------------------------------------------------------------- 
  Line   wp-admin/load-scripts.php                                             
 ------ ---------------------------------------------------------------------- 
  68     Function get_file not found.                                          
         🪪  function.notFound                                                 
         💡  Learn more at https://phpstan.org/user-guide/discovering-symbols  
         at src/wp-admin/load-scripts.php:68                                   
 ------ ---------------------------------------------------------------------- 

 ------ ---------------------------------------------------------------------- 
  Line   wp-admin/load-styles.php                                              
 ------ ---------------------------------------------------------------------- 
  83     Function get_file not found.                                          
         🪪  function.notFound                                                 
         💡  Learn more at https://phpstan.org/user-guide/discovering-symbols  
         at src/wp-admin/load-styles.php:83                                    
 ------ ---------------------------------------------------------------------- 

What appears to be the issue is that I use my wordpress-develop clone for core and plugin development together. So my src/wp-content is very large. I know other contributors do this as well, so this is something which should be accounted for.

Nevertheless, the change I made is not ideal because then it doesn't check the PHP files in the root of src, like wp-login.php. I'm confused because from looking at the excludePaths config, it would seem that src/wp-content is supposed to be excluded, and yet PHPStan still seems to be scanning all the 16GB worth of files in the plugins dir.

[westonruter]

I suppose then this would necessitate adding PHPStan to Gutenberg to do the necessary checks?

[justlevine]

WordPress/gutenberg#66598 but it's been gathering dust for a while.

[westonruter]

• PR for Customizer PHPStan fixes: Fix PHPStan level 0 issues for Customizer setting subclasses by returning correct types #10952

[westonruter]

• PR for fix to user.php: Fix PHPStan error with wp_insert_user() which causes it to hang #10953

[westonruter]

@dmsnell As of 4513d92, PHPStan issues do not cause a job to fail:

And the annotations show up as warnings instead of errors:

Instead of: