Static Analyzer (PHPStan) Integration

.github/workflows/phpstan.yaml

@@ -0,0 +1,39 @@
+name: PHPStan Static Analyzer
+on: [push]
+jobs:
+  run-phpstan:
+    name: Run PHPStan
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.3'
+        extensions: json, xdebug
+        tools: composer:v2
+
+    - name: Check out code
+      uses: actions/checkout@v2
+
+    - name: Get Composer cache directory
+      id: composer-cache
+      run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+    - name: Connect downloaded dependencies with a cache in GitHub
+      uses: actions/cache@v3
+      with:
+        path: ${{ steps.composer-cache.outputs.dir }}
+        # Note: Normally, we'd use the composer.lock to generate a hash,
+        # but the lock file is currently not versioned.
+        key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
+        restore-keys: ${{ runner.os }}-composer-
+
+    - name: Install dependencies
+      run: composer install --prefer-dist
+
+    - name: Audit dependencies
+      run: composer audit
+
+    - name: Run PHPStan
+      run: vendor/bin/phpstan analyse

README.md

@@ -142,3 +142,45 @@ Read more about available features on the [Clockwork website](https://undergroun
 		<img width="150px" src="https://github.com/itsgoingd/clockwork/raw/master/.github/assets/footer.png">
 	</a>
 </p>
+
+## Hacking
+
+### PHPStan Static Analyzer Integration
+
+All code is checked for common flaws using [PHPStan](https://phpstan.org), a
+static code analyzer.
+This is executed in a Github action defined in .github/workflows/phpstan.yaml.
+
+#### Running PHPStan Locally
+
+You can execute it using `vendor/bin/phpstan analyze`.
+If you fix any of the existing flaws, you have to remove them from the
+baseline (phpstan-baseline.neon), either manually or by regenerating
+the baseline.
+If you add any flaw, first choice is of course to improve the code, but
+if the code is sound and PHPStan reports a false positive, you can also
+regenerate the baseline.
+In order to regenerate the baseline, run `vendor/bin/phpstan analyze
+--generate-baseline`.
+
+#### Troubleshooting
+
+- I get different flaws locally than those reported by the Github action:
+  This can easily happen when your local environment does not match the one
+  on Github. In particular, the PHP version, the installed extensions but
+  also packages that you have installed locally. In that case, you can't
+  easily use the local results. Perhaps the easiest way would be to use a
+  Docker container that is set up to resemble the Github environment.
+- PHPStan complains about a flaw, but I already fixed it:
+  Check the error message carefully, PHPStan will tell you if you fix a flaw,
+  but leave an exception in the baseline. In that case, remove the flaw from
+  the baseline.
+- I get complaints about some code that is totally valid:
+  Sometimes, PHPStan reports false positives, too. In that case, consider
+  filing a bug ticket (maybe it already exists even?), and add the flaw to
+  the baseline.
+- I don't have any changes at all, but still get complaints:
+  This can happen if e.g. PHPStan itself is not the same version as the one
+  executed by the Github action. Newer versions may find additional flaws
+  or maybe not flag some valid code as false positive. Since we don't lock
+  the installed version (using composer.lock), this can happen.

composer.json

@@ -37,5 +37,15 @@
                 "Clockwork": "Clockwork\\Support\\Laravel\\Facade"
             }
         }
+    },
+    "require-dev": {
+        "phpstan/phpstan": "^1.10",
+        "spaze/phpstan-disallowed-calls": "^3.0",
+        "phpstan/extension-installer": "^1.3"
+    },
+    "config": {
+        "allow-plugins": {
+            "phpstan/extension-installer": true
+        }
     }
 }