PHP third-party extensions documentation structure

.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-base-lang=extensions
+
+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

@@ -0,0 +1,28 @@
+FROM php:8.4-cli
+ARG UID=1000
+ARG GID=1000
+
+RUN apt-get update && \
+    apt-get install -y git default-jre-headless
+
+WORKDIR /var/www
+
+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 && \
+    chown -R $UID:$GID phd doc-base
+
+RUN echo 'memory_limit = 512M' >> /usr/local/etc/php/conf.d/local.ini
+
+ENV FORMAT=xhtml
+
+CMD ["sh", "-c", "\
+php doc-base/configure.php --with-base-lang=extensions && \
+exec php phd/render.php \
+  --docbook doc-base/.manual.xml \
+  --output=/var/www/extensions/output \
+  --package PHP \
+  --format ${FORMAT} \
+"]

.editorconfig

@@ -0,0 +1,12 @@
+; This file is for unifying the coding style for different editors and IDEs.
+; More information at https://editorconfig.org
+
+root = true
+
+[*.xml]
+charset = utf-8
+indent_size = 1
+indent_style = space
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true

.gitattributes

@@ -0,0 +1,2 @@
+*.xml linguist-detectable
+*.ent linguist-language=XML linguist-detectable

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,43 @@
+name: "Bug Report"
+description: "Report an issue with the PHP documentation"
+labels: ["bug"]
+
+body:
+  - type: input
+    id: affected-page
+    attributes:
+      label: "Affected page"
+      description: "Provide the URL or file path of the affected documentation page."
+      placeholder: "e.g., https://www.php.net/manual/extensions/function.strlen.php"
+    validations:
+      required: true
+
+  - type: textarea
+    id: issue-description
+    attributes:
+      label: "Issue description"
+      description: "Describe the bug, including incorrect behavior, broken links, or missing content."
+      placeholder: "Describe what's wrong or missing on the page."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: "Steps to reproduce"
+      description: "Explain how to reproduce the issue."
+      placeholder: |
+        1. Go to the page
+        2. Describe the actions
+        3. Explain the expected behavior
+    validations:
+      required: false
+
+  - type: textarea
+    id: suggested-fix
+    attributes:
+      label: "Suggested fix"
+      description: "Provide corrections or relevant references if possible."
+      placeholder: "e.g., link to correct behavior or suggested text/code."
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/documentation-improvement.yml

@@ -0,0 +1,40 @@
+name: "Documentation Improvement"
+description: "Suggest an improvement for the PHP documentation"
+labels: ["enhancement"]
+
+body:
+  - type: input
+    id: affected-page
+    attributes:
+      label: "Affected page"
+      description: "Provide the URL or file path of the documentation to improve."
+      placeholder: "e.g., https://www.php.net/manual/extensions/function.strlen.php"
+    validations:
+      required: true
+
+  - type: textarea
+    id: current-issue
+    attributes:
+      label: "Current issue"
+      description: "Explain what is wrong or lacking, such as outdated info, missing examples, or unclear explanations."
+      placeholder: "Explain why the current documentation needs improvement."
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggested-improvement
+    attributes:
+      label: "Suggested improvement"
+      description: "Provide updated content, better examples, or clarifications."
+      placeholder: "Share your proposed improvement."
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: "Additional context (optional)"
+      description: "Provide references, links, or examples from official or relevant sources."
+      placeholder: "Optional references or further explanation."
+    validations:
+      required: false

.github/dependabot.yml

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