Add PHPStan with a baseline

[pfefferle]

Proposed changes:

• Adds PHPStan (with the WordPress stubs and extension) at level 6, so new or changed PHP needs parameter and return types, and type errors fail CI. composer analyze runs it locally.
• Every method and function now declares its return type: 525 @return void, 15 with their real type, all checked by PHPStan against the return statements. That surfaced three things worth fixing on the way: Screen_Options::init was hooked with add_filter( 'init' ) instead of add_action, Update::handle_update() returned the result of the void Create::handle_create(), and the welcome checklist passed two ints to esc_html().
• A baseline freezes the 195 findings that remain: type mismatches (add_post_meta expects int, string given, an undefined Generic_Object::get_id(), conditions that are always true) to work through file by file. Fixing a listed finding does not fail the run (reportUnmatchedIgnoredErrors: false), and composer analyze:baseline regenerates the file. Array value types (array<string, mixed>) are not required; that rule alone accounted for 936 findings WordPress-style docblocks never carry.
• Three accommodations: a bootstrap for the constants the plugin defines at runtime, "class not found" ignored inside integration/ only (other plugins), and the Stream connector excluded because it extends a class from that plugin. A small WP-CLI stub covers the eight calls the CLI code makes; the official WP-CLI stubs only work with WordPress stubs up to 6.x.
• CI job mirrors the phpcs one, runs on PHP 8.3 for speed while the analysis targets 7.4. The config and baseline are export-ignored, and docs/code-linting.md has a section on it.

This is the first step of typing the collection classes; the next PR types Inbox as the template.

Other information:

• Have you written new tests for your changes, if applicable?

Testing instructions:

• composer install && composer analyze reports no errors.
• Add a method without a return type to any file under includes/ and run it again: it fails.

Changelog entry

Skip Changelog, tooling only.

• Automatically create a changelog entry from the details below.

Changelog Entry Details

Significance

• Patch
• Minor
• Major

Type

• Added - for new features
• Changed - for changes in existing functionality
• Deprecated - for soon-to-be removed features
• Removed - for now removed features
• Fixed - for any bug fixes
• Security - in case of vulnerabilities

Message

[Copilot]

🟡 Changes recommended

PHPStan 2.x must be isolated or made compatible with the PHP 7.4 Composer jobs.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds PHPStan level 6 analysis with WordPress/WP-CLI stubs, a baseline, CI integration, and documentation. A critical PHP 7.4 Composer compatibility issue remains.

Changes:

• Adds PHPStan dependencies and the composer analyze script.
• Adds configuration, bootstrap, and WP-CLI stubs.
• Adds CI enforcement and documentation.
• Excludes analysis files from exports.

File summaries

File	Summary
tests/phpstan/stubs/wp-cli.php	Provides WP-CLI class stubs.
tests/phpstan/stubs/wp-cli-utils.php	Provides WP-CLI utility stubs.
tests/phpstan/bootstrap.php	Defines runtime constants for analysis.
phpstan.neon.dist	Configures PHPStan analysis.
docs/code-linting.md	Documents PHPStan usage.
composer.json	Adds PHPStan dependencies and analysis script; PHPStan 2.x conflicts with PHP 7.4 Composer jobs.
.github/workflows/phpstan.yml	Runs PHPStan in CI.
.gitattributes	Excludes analysis files from exports.

Review details

• Files reviewed: 8/9 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

No unresolved review comments or blocking issues were identified.

Review details

• Files reviewed: 8/9 changed files
• Comments generated: 0 new
• Review effort level: Lite