PHPLIB-610: Psalm Integration (mongodb#973)

* Add base psalm configuration

* Run psalm on GitHub Actions

* Fix psalm errors

* Use development version of psalm

The upcoming release will include an updated callmap for the MongoDB classes.

* Add unfixable error to psalm baseline

* Enforce psalm errorLevel 1 for new code

Existing errors are added to the baseline, meaning that new code needs to adhere to the strictest psalm level.

* Run coding standards and static analysis checks on feature branches

* Add contribution docs for psalm

* Improve ChangeStreamIterator handling of wrapped iterator

* Specify callable explicitly in ChangeStream

* Make null coalesce within ternary more readable

* Rewrite conditional to avoid suppressing psalm errors

* Move psalm config to dist file

* Add comment about ChangeStreamIterator::getInnerIterator

.github/workflows/coding-standards.yml

@@ -5,14 +5,16 @@ on:
     branches:
       - "v*.*"
       - "master"
+      - "feature/*"
   push:
     branches:
       - "v*.*"
       - "master"
+      - "feature/*"
 
 jobs:
-  coding-standards:
-    name: "Coding Standards"
+  phpcs:
+    name: "phpcs"
     runs-on: "ubuntu-20.04"
 
     strategy:

.github/workflows/static-analysis.yml

@@ -0,0 +1,68 @@
+name: "Static Analysis"
+
+on:
+  pull_request:
+    branches:
+      - "v*.*"
+      - "master"
+      - "feature/*"
+  push:
+    branches:
+      - "v*.*"
+      - "master"
+      - "feature/*"
+
+jobs:
+  psalm:
+    name: "Psalm"
+    runs-on: "ubuntu-20.04"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.4"
+        driver-version:
+          - "mongodb/mongo-php-driver@master"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+
+      - name: Setup cache environment
+        id: extcache
+        uses: shivammathur/cache-extensions@v1
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: "mongodb-${{ matrix.driver-version }}"
+          key: "extcache-v1"
+
+      - name: Cache extensions
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.extcache.outputs.dir }}
+          key: ${{ steps.extcache.outputs.key }}
+          restore-keys: ${{ steps.extcache.outputs.key }}
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          extensions: "mongodb-${{ matrix.driver-version }}"
+          php-version: "${{ matrix.php-version }}"
+          tools: "cs2pr"
+
+      - name: "Show driver information"
+        run: "php --ri mongodb"
+
+      - name: "Cache dependencies installed with Composer"
+        uses: "actions/cache@v2"
+        with:
+          path: "~/.composer/cache"
+          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
+          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
+
+      - name: "Install dependencies with Composer"
+        run: "composer install --no-interaction --no-progress --no-suggest"
+
+      - name: "Run Psalm"
+        run: "vendor/bin/psalm --show-info=false --stats --output-format=github --threads=$(nproc)"

.gitignore

@@ -12,4 +12,7 @@ phpunit.xml
 .phpcs-cache
 phpcs.xml
 
+# psalm
+psalm.xml
+
 mongocryptd.pid

CONTRIBUTING.md

@@ -122,6 +122,32 @@ To automatically fix all fixable errors, use the `phpcbf` binary:
 $ vendor/bin/phpcbf
 ```
 
+## Running static analysis
+
+The library uses [psalm](https://psalm.dev) to run static analysis on the code
+and ensure an additional level of type safety. New code is expected to adhere
+to level 1, with a baseline covering existing issues. To run static analysis
+checks, run the `psalm` binary:
+
+```
+$ vendor/bin/psalm
+```
+
+To remove fixed errors from the baseline, you can use the `update-baseline`
+command-line argument:
+
+```
+$ vendor/bin/psalm --update-baseline
+```
+
+Note that this will not add new errors to the baseline. New errors should be
+fixed instead of being added to the technical debt, but in case this isn't
+possible it can be added to the baseline using `set-baseline`:
+
+```
+$ vendor/bin/psalm --set-baseline=psalm-baseline.xml
+```
+
 ## Documentation
 
 Documentation for the library lives in the `docs/` directory and is built with

composer.json

@@ -19,7 +19,8 @@
     "require-dev": {
         "squizlabs/php_codesniffer": "^3.6",
         "doctrine/coding-standard": "^9.0",
-        "symfony/phpunit-bridge": "^5.2"
+        "symfony/phpunit-bridge": "^5.2",
+        "vimeo/psalm": "^4.x-dev"
     },
     "autoload": {
         "psr-4": { "MongoDB\\": "src/" },