DOCSP-42819: add coding standards workflow

.github/actions/setup/action.yml

@@ -0,0 +1,52 @@
+name: Setup
+description: Sets up the build environment
+inputs:
+  php-version:
+    description: "PHP version to install"
+    required: true
+  driver-version:
+    description: "MongoDB extension version to install"
+    required: true
+  php-ini-values:
+    description: "INI values to pass along to setup-php action"
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Setup cache environment
+      id: extcache
+      uses: shivammathur/cache-extensions@v1
+      with:
+        php-version: ${{ inputs.php-version }}
+        extensions: "mongodb-${{ inputs.driver-version }}"
+        key: "extcache-v1"
+
+    - name: Cache extensions
+      uses: actions/cache@v4
+      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-${{ inputs.driver-version }}"
+        php-version: "${{ inputs.php-version }}"
+        tools: cs2pr
+        ini-values: "${{ inputs.php-ini-values }}"
+
+    - name: Show driver information
+      run: "php --ri mongodb"
+      shell: bash
+
+    - name: Install dependencies with Composer
+      uses: ramsey/[email protected]
+      with:
+        # Revert when psalm supports PHP 8.4
+        # composer-options: "--no-suggest"
+        composer-options: "--no-suggest ${{ inputs.php-version == '8.4'
+        && '--ignore-platform-req=php+' || '' }}"

.github/workflows/coding-standards.yml

@@ -0,0 +1,32 @@
+name: "Coding Standards"
+
+on:
+  pull_request:
+    paths:
+      - "source/**/*.php"
+      - ".github/workflows/*.yml"
+
+env:
+  PHP_VERSION: "8.2"
+  # TODO: change to "stable" once 1.20.0 is released
+  # DRIVER_VERSION: "stable"
+  DRIVER_VERSION: "mongodb/mongo-php-driver@master"
+
+jobs:
+  phpcs:
+    name: "phpcs"
+    runs-on: "ubuntu-22.04"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v4"
+
+      - name: "Setup"
+        uses: "./.github/actions/setup"
+        with:
+          php-version: ${{ env.PHP_VERSION }}
+          driver-version: ${{ env.DRIVER_VERSION }}
+
+      # The -q option is required until phpcs v4 is released
+      - name: "Run PHP_CodeSniffer"
+        run: "vendor/bin/phpcs -q --no-colors --report=checkstyle | cs2pr"

.github/workflows/static-analysis.yml

@@ -0,0 +1,58 @@
+name: "Static Analysis"
+
+on:
+  pull_request:
+    paths:
+      - "source/**/*.php"
+      - ".github/workflows/*.yml"
+  workflow_call:
+    inputs:
+      ref:
+        description: "The git ref to check"
+        type: string
+        required: true
+
+env:
+  PHP_VERSION: "8.2"
+  # TODO: change to "stable" once 1.20.0 is released
+  # DRIVER_VERSION: "stable"
+  DRIVER_VERSION: "mongodb/mongo-php-driver@master"
+
+jobs:
+  psalm:
+    name: "Psalm"
+    runs-on: "ubuntu-22.04"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v4"
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.ref }}
+
+      - name: "Get SHA hash of checked out ref"
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        run: |
+          echo CHECKED_OUT_SHA=$(git rev-parse HEAD) >> $GITHUB_ENV
+
+      - name: "Setup"
+        uses: "./.github/actions/setup"
+        with:
+          php-version: ${{ env.PHP_VERSION }}
+          driver-version: ${{ env.DRIVER_VERSION }}
+
+      - name: "Run Psalm"
+        run: "vendor/bin/psalm --show-info=false --stats --output-format=github --threads=$(nproc) --report=psalm.sarif"
+
+      - name: "Upload SARIF report"
+        if: ${{ github.event_name != 'workflow_dispatch' }}
+        uses: "github/codeql-action/upload-sarif@v3"
+        with:
+          sarif_file: psalm.sarif
+
+      - name: "Upload SARIF report"
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        uses: "github/codeql-action/upload-sarif@v3"
+        with:
+          sarif_file: psalm.sarif
+          ref: ${{ inputs.ref }}
+          sha: ${{ env.CHECKED_OUT_SHA }}

.gitignore

@@ -5,3 +5,6 @@ build
 *giza.log
 source/*
 backups/*
+vendor/
+composer.lock
+.phpcs-cache

composer.json

@@ -0,0 +1,18 @@
+{
+  "name": "mongodb/docs-php-library",
+  "description": "MongoDB PHP Library Documentation",
+  "require": {
+    "ext-mongodb": "^1.19",
+    "mongodb/mongodb": "^1.19"
+  },
+  "require-dev": {
+    "doctrine/coding-standard": "^12.0",
+    "squizlabs/php_codesniffer": "^3.7",
+    "vimeo/psalm": "^5.13"
+  },
+  "config": {
+    "allow-plugins": {
+      "dealerdirect/phpcodesniffer-composer-installer": true
+    }
+  }
+}

phpcs.xml

@@ -0,0 +1,126 @@
+<?xml version="1.0"?>
+<ruleset>
+    <arg name="basepath" value="." />
+    <arg name="extensions" value="php" />
+    <arg name="parallel" value="80" />
+    <arg name="cache" value=".phpcs-cache" />
+    <arg name="colors" />
+
+    <!-- Ignore warnings (n), show progress of the run (p), and show sniff names (s) -->
+    <arg value="nps"/>
+
+    <file>source/examples</file>
+
+    <!-- Target minimum supported PHP version -->
+    <config name="php_version" value="80100"/>
+
+    <!-- ****************************************** -->
+    <!-- Import rules from doctrine/coding-standard -->
+    <!-- ****************************************** -->
+    <rule ref="Doctrine">
+        <!-- No namespace for examples -->
+        <exclude name="PSR1.Classes.ClassDeclaration.MissingNamespace" />
+
+        <!-- Can cause subtle BC breaks -->
+        <exclude name="SlevomatCodingStandard.TypeHints.DeclareStrictTypes" />
+
+
+        <!-- **************************************** -->
+        <!-- Exclude sniffs that force unwanted style -->
+        <!-- **************************************** -->
+        <exclude name="Generic.Formatting.MultipleStatementAlignment" />
+        <exclude name="Squiz.Commenting.FunctionComment.ThrowsNoFullStop" />
+        <exclude name="SlevomatCodingStandard.TypeHints.UnionTypeHintFormat.DisallowedShortNullable" />
+
+        <!-- ********************* -->
+        <!-- Exclude broken sniffs -->
+        <!-- ********************* -->
+
+        <!-- Sniff currently broken when casting arrays, see https://github.com/squizlabs/PHP_CodeSniffer/issues/2937#issuecomment-615498860 -->
+        <exclude name="Squiz.Arrays.ArrayDeclaration.ValueNoNewline" />
+
+        <!-- Disable forbidden annotation sniff as excluding @api from the list doesn't work -->
+        <exclude name="SlevomatCodingStandard.Commenting.ForbiddenAnnotations.AnnotationForbidden" />
+
+        <!-- Example file using HTML templating -->
+        <exclude name="Generic.Files.InlineHTML.Found"/>
+        <exclude name="SlevomatCodingStandard.ControlStructures.BlockControlStructureSpacing.IncorrectLinesCountAfterControlStructure"/>
+    </rule>
+
+
+    <!-- **************************************** -->
+    <!-- Enable rules not enforced by Doctrine CS -->
+    <!-- **************************************** -->
+
+    <!-- Forbid fully qualified names even for colliding names -->
+    <rule ref="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly">
+        <properties>
+            <property name="allowFallbackGlobalConstants" value="false"/>
+            <property name="allowFallbackGlobalFunctions" value="false"/>
+            <property name="allowFullyQualifiedGlobalClasses" value="false"/>
+            <property name="allowFullyQualifiedGlobalConstants" value="false"/>
+            <property name="allowFullyQualifiedGlobalFunctions" value="false"/>
+            <property phpcs-only="true" name="allowFullyQualifiedNameForCollidingClasses" value="false"/>
+            <property phpcs-only="true" name="allowFullyQualifiedNameForCollidingConstants" value="false"/>
+            <property phpcs-only="true" name="allowFullyQualifiedNameForCollidingFunctions" value="false"/>
+            <property name="searchAnnotations" value="true"/>
+        </properties>
+    </rule>
+
+
+    <!-- ****************************************************** -->
+    <!-- Don't require annotations to specify traversable types -->
+    <!-- ****************************************************** -->
+    <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingTraversableTypeHintSpecification" />
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingTraversableTypeHintSpecification" />
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingTraversableTypeHintSpecification" />
+    </rule>
+
+
+    <!-- ************************************************************************** -->
+    <!-- Require type hints for all parameters, properties, and return types in src -->
+    <!-- ************************************************************************** -->
+    <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingAnyTypeHint">
+        <exclude-pattern>tests</exclude-pattern>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingAnyTypeHint">
+        <exclude-pattern>tests</exclude-pattern>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingAnyTypeHint">
+        <exclude-pattern>tests</exclude-pattern>
+    </rule>
+
+
+    <!-- *********************************************************** -->
+    <!-- Require native type hints for all code without a BC promise -->
+    <!-- *********************************************************** -->
+    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint">
+        <exclude-pattern>src</exclude-pattern>
+    </rule>
+
+
+    <!-- ************************************************************* -->
+    <!-- Ignore errors for certain files where this is part of the API -->
+    <!-- ************************************************************* -->
+    <rule ref="PSR1.Methods.CamelCapsMethodName.NotCamelCaps">
+        <exclude-pattern>/src/GridFS/StreamWrapper</exclude-pattern>
+        <exclude-pattern>/tests/DocumentationExamplesTest.php</exclude-pattern>
+        <exclude-pattern>/tests/GridFS/UnusableStream.php</exclude-pattern>
+        <exclude-pattern>/tests/SpecTests/ClientSideEncryption/Prose*</exclude-pattern>
+    </rule>
+    <rule ref="PSR1.Classes.ClassDeclaration.MultipleClasses">
+        <exclude-pattern>/examples</exclude-pattern>
+        <exclude-pattern>/tests/PHPUnit/ConstraintTrait.php</exclude-pattern>
+    </rule>
+    <rule ref="Squiz.Classes.ClassFileName.NoMatch">
+        <exclude-pattern>/examples</exclude-pattern>
+    </rule>
+    <rule ref="Squiz.Classes.ValidClassName.NotCamelCaps">
+        <exclude-pattern>/tests/SpecTests/ClientSideEncryption/Prose*</exclude-pattern>
+    </rule>
+</ruleset>

psalm-baseline.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<files psalm-version="5.25.0@01a8eb06b9e9cc6cfb6a320bf9fb14331919d505">
+  <file src="source/examples/aws-lambda/index.php">
+    <MissingFile>
+      <code><![CDATA[require_once __DIR__ . '/vendor/autoload.php']]></code>
+    </MissingFile>
+    <MixedAssignment>
+      <code><![CDATA[$planet]]></code>
+    </MixedAssignment>
+    <PossiblyFalseArgument>
+      <code><![CDATA[$uri]]></code>
+    </PossiblyFalseArgument>
+  </file>
+  <file src="source/examples/codecs/handling-data-types/DateTimeCodec.php">
+    <MissingTemplateParam>
+      <code><![CDATA[DecodeIfSupported]]></code>
+      <code><![CDATA[EncodeIfSupported]]></code>
+    </MissingTemplateParam>
+    <MixedAssignment>
+      <code><![CDATA[$dateTime]]></code>
+    </MixedAssignment>
+    <MixedMethodCall>
+      <code><![CDATA[get]]></code>
+      <code><![CDATA[get]]></code>
+      <code><![CDATA[getName]]></code>
+      <code><![CDATA[getTimezone]]></code>
+      <code><![CDATA[setTimeZone]]></code>
+      <code><![CDATA[toDateTime]]></code>
+    </MixedMethodCall>
+  </file>
+  <file src="source/examples/codecs/handling-documents/disabling-codec.php">
+    <MixedMethodCall>
+      <code><![CDATA[aggregate]]></code>
+      <code><![CDATA[findOne]]></code>
+    </MixedMethodCall>
+    <PossiblyUndefinedVariable>
+      <code><![CDATA[$filter]]></code>
+      <code><![CDATA[$pipeline]]></code>
+    </PossiblyUndefinedVariable>
+    <UndefinedGlobalVariable>
+      <code><![CDATA[$collection]]></code>
+      <code><![CDATA[$collection]]></code>
+    </UndefinedGlobalVariable>
+  </file>
+  <file src="source/examples/codecs/handling-embedded-documents/AddressCodec.php">
+    <MissingTemplateParam>
+      <code><![CDATA[DecodeIfSupported]]></code>
+      <code><![CDATA[EncodeIfSupported]]></code>
+    </MissingTemplateParam>
+    <MixedMethodCall>
+      <code><![CDATA[get]]></code>
+      <code><![CDATA[get]]></code>
+      <code><![CDATA[get]]></code>
+      <code><![CDATA[get]]></code>
+    </MixedMethodCall>
+  </file>
+</files>

psalm.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0"?>
+<psalm
+        errorLevel="1"
+        errorBaseline="psalm-baseline.xml"
+        resolveFromConfigFile="true"
+        findUnusedBaselineEntry="true"
+        findUnusedCode="false"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://getpsalm.org/schema/config"
+        xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+>
+    <projectFiles>
+        <directory name="source/examples" />
+        <ignoreFiles>
+            <directory name="vendor" />
+        </ignoreFiles>
+    </projectFiles>
+<!--
+    <stubs>
+        <file name="stubs/BSON/Document.stub.php"/>
+        <file name="stubs/BSON/Iterator.stub.php"/>
+        <file name="stubs/BSON/PackedArray.stub.php"/>
+    </stubs>
+-->
+    <issueHandlers>
+        <!-- This is often the result of type checks due to missing native types -->
+        <DocblockTypeContradiction errorLevel="info" />
+
+        <!-- If the result of getenv is falsy, using the default URI is fine -->
+        <RiskyTruthyFalsyComparison errorLevel="suppress"/>
+
+        <!-- The same class can be defined in multiple examples -->
+        <DuplicateClass errorLevel="suppress" />
+        <MixedArgument errorLevel="suppress" />
+        <MixedPropertyFetch errorLevel="suppress" />
+    </issueHandlers>
+</psalm>