Skip to content

Analyse the whole project with PHPStan by default - #1244

Open
Kanti wants to merge 1 commit into
phpro:v2.xfrom
Kanti:ccr-377c09f1-bxqh6w
Open

Kanti wants to merge 1 commit into
phpro:v2.xfrom
Kanti:ccr-377c09f1-bxqh6w

Conversation

@Kanti

@Kanti Kanti commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor
Q A
Branch v2.x
Bug fix? no
New feature? no
BC breaks? yes
Deprecations? no
Documented? yes
Fixed tickets -

Follow-up of #1238. PHPStan recommends to always analyse the whole project (blog post, see also phpstan/phpstan#15704 (comment)): a change in one file can cause errors in other files, e.g. a changed method signature that breaks its callers, and a run on a list of files doesn't report ignoreErrors entries that no longer match. With the result cache, a run on the whole project is usually not slower.

This PR:

  • changes the default of the use_grumphp_paths option of the phpstan task from true to false, so PHPStan analyses the paths from its own configuration;
  • skips the task without use_grumphp_paths when none of the changed files triggers it (triggered_by, ignore_patterns, force_patterns). Before, the task ran on every commit with use_grumphp_paths: false, e.g. also for a commit that only changes README.md;
  • documents the recommendation and the trade-offs.

BC impact

The new default changes the behaviour for everyone who doesn't set use_grumphp_paths:

  • Errors in files that aren't part of the commit block the commit too. Without a result cache, the first run is slower.
  • PHPStan needs paths in its configuration, otherwise it fails with "At least one path must be specified to analyse".
  • ignore_patterns no longer excludes files from the analysis, only from triggering the task. Use excludePaths in the PHPStan configuration instead.

use_grumphp_paths: true keeps the old behaviour. If you'd rather not change the default in 2.x, I can split this up: the skip fix can go into 2.x on its own, and the new default into the next major version.

Tested manually with PHPStan 2.3.5

  • grumphp run analyses the whole project, without file arguments.
  • A commit that only changes README.md skips the task. Before, PHPStan ran and blocked the commit.
  • A commit that only changes B.php also reports the error in A.php.
  • With use_grumphp_paths: true, only the changed B.php is analysed.

New Task Checklist:

  • Are the dependencies added to the composer.json suggestions? (phpstan/phpstan is already suggested)
  • Is the doc/tasks.md file updated? (PHPStan is already listed, no change needed)
  • Are the task parameters documented? (use_grumphp_paths, ignore_patterns, force_patterns and triggered_by in doc/tasks/phpstan.md)
  • Is the task registered in the tasks.yml file? (already registered)
  • Does the task contains phpunit tests? (test/Unit/Task/PhpStanTest.php)
  • Is the configuration having logical allowed types? (unchanged)
  • Does the task run in the correct context? (unchanged: pre-commit and run)
  • Is the run() method readable?
  • Is the run() method using the configuration correctly?
  • Are all CI services returning green?

PHPStan recommends to always analyse the whole project: a change in one
file can cause errors in other files, and a run on a list of files does
not report ignoreErrors entries that no longer match. With the result
cache, a run on the whole project is usually not slower.

The use_grumphp_paths option of the phpstan task now defaults to false,
so PHPStan analyses the paths from its own configuration. The task is
now also skipped without use_grumphp_paths when none of the changed
files triggers it, instead of running on every commit.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant