CI and Mega-Linter with PHPStan

[llaville]

After a quick enhancement guide about Mega-Linter with PHPCS, two days ago in llaville/php-compatinfo-db project ...

Today I'll present my solution to fix issue oxsecurity/megalinter#725

TL;DR (unless you really want it ;-)

Pre-requis

• We are agree that PHPStan default rule level is zero as specified in user guide

• We are agree that the default PHPStan config file is now called TEMPLATES/phpstan.neon.dist instead of TEMPLATES/phpstan.neon

• Current version of Mega-Linter tested 4.47.0-dev since commit cf01fd2

List of potential issues we can found when using PHPStan linter

For demo, and follow examples, we will use the llaville/docker-php-toolbox repository.

Step 1: Install only source code with Git

git clone https://github.com/llaville/docker-php-toolbox.git

Step 2: Define a .mega-linter.yml config file with only PHP_PHPSTAN linter active

SHOW_ELAPSED_TIME: true
ENABLE:
    - PHP
DISABLE_LINTERS:
    - PHP_PSALM
    - PHP_PHPCS
    - PHP_BUILTIN

Step 3: Run Mega-Linter on source code docker-php-toolbox folder.

You can see before analysis, that ML found 33 PHP files

- File extensions: .php
Kept [33] files on [264] found files

+----MATCHING LINTERS--+----------+----------------+------------+
| Descriptor | Linter  | Criteria | Matching files | Format/Fix |
+------------+---------+----------+----------------+------------+
| PHP        | phpstan | .php     | 33             | no         |
+------------+---------+----------+----------------+------------+

That's TRUE, and we can verify this result with following commands:

find bin -name *.php  | wc
find config -name *.php  | wc
find src -name *.php  | wc

That gave us :

+------------+---------+
| Directory  | Count   |
+------------+---------+
| bin        | 1       |
| config     | 3       |
| src        | 29      |
+------------+---------+

And finally, more than 20 seconds later

It seems slow, and we have Errors detected (that is not true, as we can see soon)

+----SUMMARY-+---------+-------+-------+--------+--------------+
| Descriptor | Linter  | Files | Fixed | Errors | Elapsed time |
+------------+---------+-------+-------+--------+--------------+
| ❌ PHP     | phpstan |    33 |       |     30 |       20.84s |
+------------+---------+-------+-------+--------+--------------+

Question: Why did we found errors.

Answer: Because PHPStan needs to be able to locate symbols. And since v0.12.26 it uses Discovering Symbols feature

In summary, that means we always HAVE TO install Composer Dependencies (if project have it), before running analysis with PHPStan.

Step 4: Install Composer Dependencies with command: composer update

You should have a vendor directory with 491 php files. Confirmed by command:

find vendor -name *.php  | wc

So in total we have 524 php files in project.

Step 5: Run Mega-Linter analysis again without changing anything else

You can see before analysis, that ML found 524 PHP files

- File extensions: .php
Kept [524] files on [853] found files

+----MATCHING LINTERS--+----------+----------------+------------+
| Descriptor | Linter  | Criteria | Matching files | Format/Fix |
+------------+---------+----------+----------------+------------+
| PHP        | phpstan | .php     | 524            | no         |
+------------+---------+----------+----------------+------------+

And finally, more than 5 minutes later

It seems slow, and we have Errors detected (that is not true, as we can see soon)

+----SUMMARY-+---------+-------+-------+--------+--------------+
| Descriptor | Linter  | Files | Fixed | Errors | Elapsed time |
+------------+---------+-------+-------+--------+--------------+
| ❌ PHP     | phpstan |   524 |       |    404 |      321.01s |
+------------+---------+-------+-------+--------+--------------+

Step 6: First fix is to exclude Composer dependencies from analysis

Add in your .mega-linter.yml config file, following entry:

EXCLUDED_DIRECTORIES: ["vendor"]

NOTE I recommand also to exclude GIT config folder EXCLUDED_DIRECTORIES: [".git", "vendor"]

That is faster than previous, and but not yet correct, because some errors were detected

+----SUMMARY-+---------+-------+-------+--------+--------------+
| Descriptor | Linter  | Files | Fixed | Errors | Elapsed time |
+------------+---------+-------+-------+--------+--------------+
| ❌ PHP     | phpstan |    33 |       |     30 |       19.63s |
+------------+---------+-------+-------+--------+--------------+

Step 7: Second fix is to set Discovering Symbols feature of PHPStan

Declare a custom PHPStan config file in your .mega-linter.yml

PHP_PHPSTAN_CONFIG_FILE: "phpstan.neon"

With contents:

parameters:
    level: 6
    bootstrapFiles:
        - /tmp/lint/vendor/autoload.php
    excludePaths:
        - /tmp/lint/vendor

at the root of source code.
We have raise up rule level from 0 to 6 (but it's not mandatory for demo, just for the project itself)

We have added excludePaths, just in case you forgot to exclude vendor as previously seen with

EXCLUDED_DIRECTORIES: ["vendor"]

And run Mega-Linter again, to finally see !

+----SUMMARY-+---------+-------+-------+--------+--------------+
| Descriptor | Linter  | Files | Fixed | Errors | Elapsed time |
+------------+---------+-------+-------+--------+--------------+
| ✅ PHP     | phpstan |    33 |       |      0 |       23.93s |
+------------+---------+-------+-------+--------+--------------+

It's not really fast, but at least results are correct !

Remember how the linting is performed

Step 8: Third fix, if you want to improve perf, switch to project mode

In your .mega-linter.yml config file, add:

PHP_PHPSTAN_CLI_LINT_MODE: project

And specify in your phpstan.neon config file, paths to scan:

parameters:
    level: 6
    bootstrapFiles:
        - /tmp/lint/vendor/autoload.php
    excludePaths:
        - /tmp/lint/vendor
    paths:
        - bin/
        - config/
        - src/

Run Mega-Linter once again, and look at final results.

+----SUMMARY-+---------+---------+-------+--------+--------------+
| Descriptor | Linter  |   Files | Fixed | Errors | Elapsed time |
+------------+---------+---------+-------+--------+--------------+
| ✅ PHP     | phpstan | project |       |      0 |        2.79s |
+------------+---------+---------+-------+--------+--------------+

Amazing :)

Hope you've enjoy this walkthrough

[llaville]

A little enhancement, to allow both locally docker run and Github Action Workflow working in same way.

Remember that the difference to location containing files to lint :

• if you are running locally it's identified by DEFAULT_WORKSPACE ( = /tmp/lint )
• if you are running GA it's identified by GITHUB_WORKSPACE ( = /github/workspace )

In Step 7, we have used hardcoded path (using DEFAULT_WORKSPACE).

It's time now to use the expanding paths feature of PHPStan

And contents become

parameters:
    level: 6
    bootstrapFiles:
        - %rootDir%/../../autoload.php
    excludePaths:
        - %rootDir%/../../
    paths:
        - bin/
        - config/
        - src/

[llaville]

Finally after lot of tests with different context, using expanding paths feature of PHPStan is not the solution.

Main reason: PHPStan is installed as global (see Mega-Linter Dockerfile implementation)
And the vendor directory identified by %rootDir%/../.. is not the application version you want to scan !

Second reason: current working directory in file, and list_of_files mode is not the same (workspace) as in project mode

So the fix that will be proposed to solve oxsecurity/megalinter#725 can be summarized to :

• remove expanding paths in TEMPLATES/phpstan.neon.dist

parameters:
    level: 0
    bootstrapFiles:
        - vendor/autoload.php
    excludePaths:
        - vendor/

Add a pre command to copy TEMPLATES/phpstan.neon.dist in workspace only if it does not exists in megalinter/descriptors/php.megalinter-descriptor.yml

linters:
  - linter_name: phpstan
    name: PHP_PHPSTAN
    config_file_name: phpstan.neon.dist

    pre_commands:
      - command: "[ ! -f phpstan.neon.dist ] && cp /action/lib/.automation/phpstan.neon.dist phpstan.neon.dist"
        cwd: workspace