Merge branch 'master' into patch-2

Author: shaedrich

.devcontainer/build.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+set -e
+
+FORMAT="${1:-xhtml}"
+
+case "$FORMAT" in
+  xhtml) DOCROOT="output/php-chunked-xhtml" ;;
+  php)   DOCROOT="../web-php" ;;
+  *)     echo "Usage: $0 [xhtml|php]" >&2; exit 1 ;;
+esac
+
+php ../doc-base/configure.php \
+    --disable-libxml-check \
+    --enable-xml-details \
+    --redirect-stderr-to-stdout \
+    --with-lang=en
+
+php -d memory_limit=512M ../phd/render.php \
+    --docbook ../doc-base/.manual.xml \
+    --output ./output \
+    --package PHP \
+    --format "$FORMAT"
+
+# Restart any existing server, then launch the new one in its own session so
+# Ctrl+C in the debug terminal only kills the log tail below. The server keeps
+# running until the next build replaces it (or the container shuts down).
+#
+# auto_prepend_file rewrites $_SERVER from the request's Host header so the PHP
+# format's $MYSITE-built URLs work behind Codespaces / other port forwarders.
+LOG="/tmp/php-server-${FORMAT}.log"
+pkill -f 'php -S 0.0.0.0:8080' 2>/dev/null || true
+PREPEND="$(cd "$(dirname "$0")" && pwd)/server-prepend.php"
+setsid nohup php -d "auto_prepend_file=$PREPEND" -S 0.0.0.0:8080 -t "$DOCROOT" \
+    >"$LOG" 2>&1 </dev/null &
+SERVER_PID=$!
+
+cat <<EOF
+
+  Server: http://localhost:8080  (pid $SERVER_PID, doc root: $DOCROOT)
+  Logs:   $LOG
+  Ctrl+C exits this tail; the server keeps running.
+
+EOF
+
+exec tail -f "$LOG"

.devcontainer/devcontainer.json

@@ -0,0 +1,58 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/php
+{
+  "name": "PHP",
+  "image": "mcr.microsoft.com/devcontainers/php:8.4-trixie",
+
+  // Features to add to the dev container. More info: https://containers.dev/features.
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/java:1": {
+      "version": "lts",
+      "installGradle": false,
+      "installMaven": false
+    }
+  },
+
+  // Configure tool-specific properties.
+  "customizations": {
+    // Configure properties specific to VS Code.
+    "vscode": {
+      "extensions": [
+        "editorconfig.editorconfig",
+        "redhat.vscode-xml"
+      ],
+      // Workspace-level launch config
+      "settings": {
+        "launch": {
+          "version": "0.2.0",
+          "configurations": [
+            {
+              "name": "Build XHTML & serve",
+              "type": "node-terminal",
+              "request": "launch",
+              "command": ".devcontainer/build.sh xhtml"
+            },
+            {
+              "name": "Build PHP web & serve",
+              "type": "node-terminal",
+              "request": "launch",
+              "command": ".devcontainer/build.sh php"
+            }
+          ]
+        }
+      }
+    }
+  },
+
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  "forwardPorts": [
+    8080
+  ],
+
+  // Use 'postCreateCommand' to run commands after the container is created.
+  "postCreateCommand": "sudo .devcontainer/post-create.sh",
+
+  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+  // "remoteUser": "root"
+}

.devcontainer/post-create.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+set -e
+
+WORKSPACE="$(cd "$(dirname "$0")/.." && pwd)"
+PARENT="$(dirname "$WORKSPACE")"
+OWNER="$(stat -c '%U' "$WORKSPACE")"
+
+# Clone doc-base, phd, and web-php as siblings of doc-en.
+[ -d "$PARENT/doc-base" ] || sudo -u "$OWNER" git -C "$PARENT" clone --depth 1 https://github.com/php/doc-base.git
+[ -d "$PARENT/phd" ]      || sudo -u "$OWNER" git -C "$PARENT" clone --depth 1 https://github.com/php/phd.git
+[ -d "$PARENT/web-php" ]  || sudo -u "$OWNER" git -C "$PARENT" clone --depth 1 https://github.com/php/web-php.git
+
+# doc-base's configure.php looks for the language source as a sibling directory
+[ -e "$PARENT/en" ] || sudo -u "$OWNER" ln -s "$WORKSPACE" "$PARENT/en"
+
+# Xdebug degrades performance and is not needed for the build, so disable it by default.
+rm -f /usr/local/etc/php/conf.d/xdebug.ini
+
+# Pre-create the served directories
+sudo -u "$OWNER" mkdir -p "$WORKSPACE/output/php-chunked-xhtml" "$WORKSPACE/output/php-web"
+sudo -u "$OWNER" rm -rf "$PARENT/web-php/manual/en"
+sudo -u "$OWNER" ln -s "$WORKSPACE/output/php-web" "$PARENT/web-php/manual/en"
+
+cat <<'EOF'
+
+  Devcontainer ready.
+
+  Build & serve:     F5 > "Build XHTML & serve"   (or "Build PHP web & serve")
+
+  View them:         http://localhost:8080
+
+EOF

.devcontainer/server-prepend.php

@@ -0,0 +1,15 @@
+<?php
+
+// This file rewrites $_SERVER from the request's Host header so the PHP
+// format's $MYSITE-built URLs work behind Codespaces / other port forwarders.
+
+$forwardedHttps = ($_SERVER['HTTP_X_FORWARDED_PROTO'] ?? '') === 'https';
+$hostHeader = $_SERVER['HTTP_X_FORWARDED_HOST'] ?? $_SERVER['HTTP_HOST'] ?? '';
+
+if ($hostHeader !== '') {
+    $_SERVER['HTTP_HOST'] = $hostHeader;
+}
+
+if ($forwardedHttps) {
+    $_SERVER['HTTPS'] = 'on';
+}

.docker/Dockerfile

@@ -1,4 +1,6 @@
 FROM php:8.2-cli
+ARG UID=1000
+ARG GID=1000
 
 RUN apt-get update && \
     apt-get install -y git default-jre-headless
@@ -9,11 +11,18 @@ ADD https://api.github.com/repos/php/phd/git/refs/heads/master version-phd.json
 ADD https://api.github.com/repos/php/doc-base/git/refs/heads/master version-doc-base.json
 
 RUN git clone --depth 1 https://github.com/php/phd.git &&  \
-    git clone --depth 1 https://github.com/php/doc-base.git
+    git clone --depth 1 https://github.com/php/doc-base.git && \
+    chown -R $UID:$GID phd doc-base
 
 RUN echo 'memory_limit = 512M' >> /usr/local/etc/php/conf.d/local.ini
 
 ENV FORMAT=xhtml
 
-CMD php doc-base/configure.php --disable-segfault-error && \
-    php phd/render.php --docbook doc-base/.manual.xml --output=/var/www/en/output --package PHP --format ${FORMAT}
+CMD ["sh", "-c", "\
+php doc-base/configure.php && \
+exec php phd/render.php \
+  --docbook doc-base/.manual.xml \
+  --output=/var/www/en/output \
+  --package PHP \
+  --format ${FORMAT}\
+"]

.github/dependabot.yml

@@ -1,5 +1,9 @@
 version: 2
 updates:
+  - package-ecosystem: "devcontainers"
+    directory: "/"
+    schedule:
+      interval: "weekly"
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/workflows/check-whitespace.yml

@@ -0,0 +1,109 @@
+# https://docs.github.com/en/actions
+
+name: "DocBook Lint"
+
+on:
+  push:
+    branches:
+      - "master"
+  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@v7"
+        with:
+          ref: "${{ github.event.pull_request.head.sha }}"
+          path: "${{ matrix.language }}"
+          fetch-depth: 50
+
+      - name: "Checkout php/doc-base"
+        uses: "actions/checkout@v7"
+        with:
+          path: "doc-base"
+          repository: "php/doc-base"
+
+      - name: "Checkout php/docbook-cs"
+        uses: "actions/checkout@v7"
+        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

.github/workflows/docbook-cs.yaml

@@ -24,20 +24,20 @@ jobs:
 
     steps:
       - name: "Checkout php/doc-${{ matrix.language }}"
-        uses: "actions/checkout@v5"
+        uses: "actions/checkout@v7"
         with:
           path: "${{ matrix.language }}"
           repository: "php/doc-${{ matrix.language }}"
 
       - name: "Checkout php/doc-en as fallback"
         if: "matrix.language != 'en'"
-        uses: "actions/checkout@v5"
+        uses: "actions/checkout@v7"
         with:
           path: "en"
           repository: "php/doc-en"
 
       - name: "Checkout php/doc-base"
-        uses: "actions/checkout@v5"
+        uses: "actions/checkout@v7"
         with:
           path: "doc-base"
           repository: "php/doc-base"
@@ -51,7 +51,7 @@ jobs:
         run: "php8.1 doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-lang=${{ matrix.language }}"
 
       - name: "Upload .manual.xml"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: .manual.xml
           path: doc-base/.manual.xml

.github/workflows/integrate.yaml

@@ -8,11 +8,12 @@
 # For more information, see the GitHub CODEOWNERS documentation:
 # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 
-/reference/dom @nielsdos
+/reference/dom @ndossche
 /reference/hash @TimWolla
-/reference/libxml @nielsdos
+/reference/libxml @ndossche
 /reference/mysqli @kamil-tekiela
 /reference/mysqlnd @kamil-tekiela
 /reference/pdo @kamil-tekiela
 /reference/pdo_mysql @kamil-tekiela
 /reference/random @TimWolla
+/reference/uri @TimWolla