[DOC-CVS] [doc-en] master: Add docbook-cs (#5524)

Author: Jordi Kroon (jordikroon)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-06-13T22:43:30+02:00

Commit: https://github.com/php/doc-en/commit/23e4fb409edaebf41e35ca682f80c1d7e643123d
Raw diff: https://github.com/php/doc-en/commit/23e4fb409edaebf41e35ca682f80c1d7e643123d.diff

Add docbook-cs (#5524)

Changed paths:
  A  .github/workflows/docbook-cs.yaml
  A  docbookcs.xml
  D  .github/workflows/check-whitespace.yml


Diff:

diff --git a/.github/workflows/check-whitespace.yml b/.github/workflows/check-whitespace.yml
deleted file mode 100644
index 91c5e6419562..000000000000
--- a/.github/workflows/check-whitespace.yml
+++ /dev/null
@@ -1,29 +0,0 @@
-name: check-whitespace
-
-# Get the repository with all commits to ensure that we can analyze
-# all of the commits contributed via the Pull Request.
-# Process `git log --check` output to extract just the check errors.
-# Exit with failure upon white-space issues.
-
-on:
-  pull_request:
-    types: [opened, synchronize]
-
-permissions:
-  contents: read
-
-jobs:
-  check-whitespace:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - run: |
-          git config --global user.name "check-whitespace"
-          git config --global user.email "[email protected]"
-      - run: git checkout ${{github.event.pull_request.base.sha}}
-      - run: git merge --squash ${{github.event.pull_request.head.sha}}
-      - run: git commit -m "Squashed"
-      - run: git log --check HEAD^..HEAD
diff --git a/.github/workflows/docbook-cs.yaml b/.github/workflows/docbook-cs.yaml
new file mode 100644
index 000000000000..1af8eead7f5a
--- /dev/null
+++ b/.github/workflows/docbook-cs.yaml
@@ -0,0 +1,107 @@
+# https://docs.github.com/en/actions
+
+name: "DocBook Lint"
+
+on:
+  push:
+  pull_request:
+    branches:
+      - "master"
+
+permissions:
+  contents: "read"
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  docbook-cs:
+    name: "DocBook Style Check"
+    runs-on: "ubuntu-latest"
+
+    env:
+      # Base commit to diff against: PR base on pull_request, pre-push tip on push.
+      BASE_SHA: |-
+        ${{
+          case(
+            github.event_name == 'pull_request', github.event.pull_request.base.sha,
+            github.event_name == 'push', github.event.before,
+            'INVALID'
+          )
+        }}
+
+    strategy:
+      matrix:
+        language:
+          - "en"
+
+    steps:
+      - name: "Checkout php/doc-${{ matrix.language }}"
+        uses: "actions/checkout@v6"
+        with:
+          ref: "${{ github.event.pull_request.head.sha }}"
+          path: "${{ matrix.language }}"
+          fetch-depth: 50
+
+      - name: "Checkout php/doc-base"
+        uses: "actions/checkout@v6"
+        with:
+          path: "doc-base"
+          repository: "php/doc-base"
+
+      - name: "Checkout php/docbook-cs"
+        uses: "actions/checkout@v6"
+        with:
+          path: "docbook-cs"
+          repository: "php/docbook-cs"
+
+      - name: "Fetch diff base"
+        working-directory: "${{ matrix.language }}"
+        run: |
+          git fetch origin "$BASE_SHA" --depth=50
+          # Deepen until the merge-base is reachable (long-lived branches)
+          for i in 1 2 3 4 5; do
+            git merge-base "$BASE_SHA" HEAD >/dev/null 2>&1 && break
+            git fetch --deepen=100 origin "$BASE_SHA"
+          done
+
+      - name: "Setup PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "8.5"
+          extensions: "dom, libxml, simplexml"
+          tools: composer, cs2pr
+
+      - name: "Build documentation"
+        run: |
+          php doc-base/configure.php \
+            --disable-libxml-check \
+            --enable-xml-details \
+            --redirect-stderr-to-stdout \
+            --with-lang=${{ matrix.language }}
+
+      - name: "Install docbook-cs"
+        working-directory: "docbook-cs"
+        run: composer install --no-interaction --no-progress
+
+      - name: "Run docbook-cs with diff"
+        working-directory: "${{ matrix.language }}"
+        run: |
+          set -o pipefail
+          git diff "$BASE_SHA"...HEAD | php ../docbook-cs/bin/docbook-cs \
+            --report=checkstyle \
+            --diff \
+            --no-colors > docbook-report.xml
+
+      - name: "Upload report"
+        if: ${{ ! cancelled() }}
+        uses: "actions/upload-artifact@v7"
+        with:
+          name: "docbook-report"
+          path: "${{ matrix.language }}/docbook-report.xml"
+
+      - name: "Annotate PR with violations"
+        if: ${{ ! cancelled() }}
+        working-directory: "${{ matrix.language }}"
+        run: cs2pr docbook-report.xml --colorize --prepend-filename
diff --git a/docbookcs.xml b/docbookcs.xml
new file mode 100644
index 000000000000..25ab97eca29e
--- /dev/null
+++ b/docbookcs.xml
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<docbookcs xmlns="https://php.github.io/docbook-cs/config"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:schemaLocation="https://php.github.io/docbook-cs/config
+                               https://php.github.io/docbook-cs/config.xsd">
+
+ <project>
+  <directory alias="doc-en">en</directory>
+  <directory>doc-base</directory>
+ </project>
+
+ <sniffs>
+  <sniff class="DocbookCS\Sniff\SimparaSniff" />
+  <sniff class="DocbookCS\Sniff\ExceptionNameSniff" />
+  <sniff class="DocbookCS\Sniff\AttributeOrderSniff" />
+  <sniff class="DocbookCS\Sniff\WhitespaceSniff" />
+ </sniffs>
+
+ <paths>
+  <path>.</path>
+ </paths>
+
+ <entities>
+  <file>contributors.ent</file>
+  <file>extensions.ent</file>
+  <file>language-defs.ent</file>
+  <file>language-snippets.ent</file>
+  <directory>../doc-base/entities/</directory>
+  <file>../doc-base/temp/file-entities.ent</file>
+  <directory>../doc-base/temp/file-entities</directory>
+ </entities>
+
+ <exclude>
+  <pattern>output/*</pattern>
+ </exclude>
+
+</docbookcs>