PHP CodeSniffer for CI workflow

.github/scripts/run-phpcs.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+readonly CHANGED_FILES="changed-source-files.txt"
+readonly PHPCS_REPORT="phpcs-report.txt"
+readonly PHPCS_AFTER_PHPCBF_REPORT="phpcs-after-phpcbf-report.txt"
+readonly PHPCS_VIOLATION_LINES="phpcs-violation-lines.txt"
+readonly CHANGED_LINE_RANGES="changed-line-ranges.txt"
+readonly PHPCS_RANGES="phpcs-ranges.txt"
+readonly DIFF_BASE_FILE="diff-base.txt"
+readonly DIFF_HEAD_FILE="diff-head.txt"
+
+echo "::group::PHPCS violations"
+set +e
+vendor/bin/phpcs \
+    --standard=phpcs.xml.dist \
+    --basepath="$(pwd)" \
+    --no-colors \
+    --file-list="$CHANGED_FILES" 2>&1 \
+    | tee "$PHPCS_REPORT"
+phpcs_exit=${PIPESTATUS[0]}
+set -e
+echo "::endgroup::"
+
+if [[ "$phpcs_exit" -eq 0 ]]; then
+    exit 0
+fi
+
+awk '
+    /^FILE: / {
+        file = $0
+        sub(/^FILE: /, "", file)
+        next
+    }
+    /^[[:space:]]*[0-9]+[[:space:]]+\|[[:space:]]+ERROR[[:space:]]+\|/ {
+        line = $1 + 0
+        print file, line
+    }
+' "$PHPCS_REPORT" > "$PHPCS_VIOLATION_LINES"
+
+while IFS= read -r file; do
+    git diff --unified=0 "$(cat "$DIFF_BASE_FILE")" "$(cat "$DIFF_HEAD_FILE")" -- "$file" \
+        | awk -v file="$file" '
+            /^@@ / {
+                split($0, parts, " ")
+                new_range = parts[3]
+                sub(/^\+/, "", new_range)
+                split(new_range, range, ",")
+                start = range[1]
+                count = range[2] == "" ? 1 : range[2]
+
+                if (count > 0) {
+                    print file, start, start + count - 1
+                }
+            }
+        '
+done < "$CHANGED_FILES" > "$CHANGED_LINE_RANGES"
+
+awk '
+    NR == FNR {
+        count[$1]++
+        start[$1, count[$1]] = $2
+        end[$1, count[$1]] = $3
+        next
+    }
+    {
+        file = $1
+        line = $2
+
+        if (!(file in all_first) || line < all_first[file]) {
+            all_first[file] = line
+        }
+        if (!(file in all_last) || line > all_last[file]) {
+            all_last[file] = line
+        }
+
+        for (i = 1; i <= count[file]; i++) {
+            if (line >= start[file, i] && line <= end[file, i]) {
+                if (!(file in changed_first) || line < changed_first[file]) {
+                    changed_first[file] = line
+                }
+                if (!(file in changed_last) || line > changed_last[file]) {
+                    changed_last[file] = line
+                }
+            }
+        }
+    }
+    END {
+        for (file in all_first) {
+            if (file in changed_first) {
+                print file, changed_first[file], changed_last[file]
+            } else {
+                print file, all_first[file], all_last[file]
+            }
+        }
+    }
+' "$CHANGED_LINE_RANGES" "$PHPCS_VIOLATION_LINES" > "$PHPCS_RANGES"
+
+echo "::group::PHPCBF fixed-code preview"
+set +e
+vendor/bin/phpcbf \
+    --standard=phpcs.xml.dist \
+    --file-list="$CHANGED_FILES" > phpcbf-report.txt 2>&1
+
+vendor/bin/phpcs \
+    --standard=phpcs.xml.dist \
+    --basepath="$(pwd)" \
+    --no-colors \
+    --file-list="$CHANGED_FILES" > "$PHPCS_AFTER_PHPCBF_REPORT" 2>&1
+phpcs_after_phpcbf_exit=$?
+set -e
+
+if [[ "$phpcs_after_phpcbf_exit" -ne 0 ]]; then
+    echo "PHPCBF could not fix every violation automatically. The preview below reflects any changes PHPCBF wrote."
+fi
+
+while IFS= read -r file; do
+    range="$(awk -v target="$file" '$1 == target { print $2 " " $3 }' "$PHPCS_RANGES")"
+    if [[ -z "$range" ]]; then
+        continue
+    fi
+
+    start_line="${range%% *}"
+    end_line="${range##* }"
+
+    echo ""
+    echo "$file:$start_line-$end_line after PHPCBF"
+    echo "----- begin fixed PHP -----"
+    sed -n "${start_line},${end_line}p" "$file"
+    echo "----- end fixed PHP -----"
+done < "$CHANGED_FILES"
+echo "::endgroup::"
+
+echo ""
+echo "Run the following command locally for PHPCBF to autofix formatting errors:"
+echo "phpcbf --standard=phpcs.xml.dist \\"
+sed 's/^/  /; $!s/$/ \\/' "$CHANGED_FILES"
+echo ""
+
+exit "$phpcs_exit"

.github/workflows/coding-standards.yml

@@ -0,0 +1,68 @@
+name: Coding Standards
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  coding-standards:
+    runs-on: ubuntu-latest
+    name: PHPCS
+    steps:
+      - name: Setup PHP
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        with:
+          coverage: none
+          php-version: '8.1'
+
+      - name: Checkout codebase
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Find changed source files
+        id: changed-source-files
+        shell: bash
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            BASE_SHA="${{ github.event.pull_request.base.sha }}"
+            HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+            DIFF_BASE="$(git merge-base "$BASE_SHA" "$HEAD_SHA")"
+          else
+            DIFF_BASE="${{ github.event.before }}"
+            HEAD_SHA="${{ github.sha }}"
+          fi
+
+          if [[ -z "$DIFF_BASE" || "$DIFF_BASE" == "0000000000000000000000000000000000000000" ]]; then
+            DIFF_BASE="$(git rev-list --max-parents=0 "$HEAD_SHA")"
+          fi
+
+          echo "$DIFF_BASE" > diff-base.txt
+          echo "$HEAD_SHA" > diff-head.txt
+
+          git diff --name-only --diff-filter=ACMRT "$DIFF_BASE" "$HEAD_SHA" -- '*.php' \
+            | grep -E '^src/' \
+            | grep -v '^src/data/' > changed-source-files.txt || true
+
+          if [[ -s changed-source-files.txt ]]; then
+            echo "has_files=true" >> "$GITHUB_OUTPUT"
+            cat changed-source-files.txt
+          else
+            echo "has_files=false" >> "$GITHUB_OUTPUT"
+            echo "No changed source files to check."
+          fi
+
+      - name: Install PHP_CodeSniffer
+        if: steps.changed-source-files.outputs.has_files == 'true'
+        run: composer require --dev squizlabs/php_codesniffer "^3.10" --no-interaction --prefer-dist --no-progress --update-with-all-dependencies
+
+      - name: Run PHP_CodeSniffer
+        if: steps.changed-source-files.outputs.has_files == 'true'
+        shell: bash
+        run: bash .github/scripts/run-phpcs.sh

CONTRIBUTING.md

@@ -87,7 +87,8 @@ we ask the same of all community contributions as well:
    ask you to sign a [Contributor License Agreement (CLA)][cla].
 2. We follow all of the relevant PSR recommendations from the [PHP Framework
    Interop Group][php-fig]. Please submit code that follows these standards.
-   The [PHP CS Fixer][cs-fixer] tool can be helpful for formatting your code.
+   The [PHP_CodeSniffer][phpcs] tool is automatically run against changed PHP
+   files in the `src` directory for submitted pull requests.
 3. We maintain a high percentage of code coverage in our unit tests. If you make
    changes to the code, please add, update, and/or remove tests as appropriate.
    Tests are run via `make test` command.
@@ -176,7 +177,7 @@ category field should exist with the value set to an empty string `""`.
 [license]: http://aws.amazon.com/apache2.0/
 [cla]: https://github.com/aws/aws-cla/blob/master/amazon-single-contribution-license.txt
 [php-fig]: http://php-fig.org
-[cs-fixer]: http://cs.sensiolabs.org/
+[phpcs]: https://github.com/PHPCSStandards/PHP_CodeSniffer
 [phpstan]: https://github.com/phpstan/phpstan
 [sphinx]: http://sphinx-doc.org/
 [restructuredtext]: http://sphinx-doc.org/rest.html

phpcs.xml.dist

@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<ruleset name="AWS SDK for PHP">
+    <description>Checks PSR-12 formatting for SDK source files.</description>
+
+    <arg name="colors"/>
+    <arg name="extensions" value="php"/>
+    <arg name="report" value="full"/>
+    <arg name="warning-severity" value="0"/>
+    <arg value="s"/>
+
+    <exclude-pattern>*/src/data/*</exclude-pattern>
+
+    <rule ref="PSR12"/>
+</ruleset>