From 3b5c87642e66ac68bdb72659d2a52aaecc741e42 Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Tue, 4 Aug 2026 21:05:10 +0200 Subject: [PATCH 1/8] PHP third-party extensions documentation structure --- .docker/Dockerfile | 28 +++++++++ .editorconfig | 12 ++++ .gitattributes | 2 + .gitignore | 4 ++ Makefile | 34 +++++++++++ bookinfo.xml | 30 ++++++++++ language-defs.ent | 120 +++++++++++++++++++++++++++++++++++++ language-snippets.ent | 3 + manual.xml | 36 +++++++++++ reference/example/book.xml | 13 ++++ 10 files changed, 282 insertions(+) create mode 100644 .docker/Dockerfile create mode 100644 .editorconfig create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100644 Makefile create mode 100644 bookinfo.xml create mode 100644 language-defs.ent create mode 100644 language-snippets.ent create mode 100644 manual.xml create mode 100644 reference/example/book.xml diff --git a/.docker/Dockerfile b/.docker/Dockerfile new file mode 100644 index 0000000..0a0e280 --- /dev/null +++ b/.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-lang=extensions --standalone && \ +exec php phd/render.php \ + --docbook doc-base/.manual.xml \ + --output=/var/www/extensions/output \ + --package PHP \ + --format ${FORMAT} \ +"] diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..5ab5087 --- /dev/null +++ b/.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 = false diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..dcc145f --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +*.xml linguist-detectable +*.ent linguist-language=XML linguist-detectable diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2da7b7f --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +entities.*.xml +output +.docker/built +temp/ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..ca70aa3 --- /dev/null +++ b/Makefile @@ -0,0 +1,34 @@ +.PHONY: * + +SHELL = /bin/sh + +CURRENT_UID := $(shell id -u) +CURRENT_GID := $(shell id -g) + +# +# If doc-base or phd exist as siblings to the current directory, add those as +# volumes to our Docker runs. +# + +PATHS := -v ${PWD}:/var/www/extensions +ifneq ($(wildcard ../doc-base/LICENSE),) + PATHS += -v ${PWD}/../doc-base:/var/www/doc-base +endif +ifneq ($(wildcard ../phd/LICENSE),) + PATHS += -v ${PWD}/../phd:/var/www/phd +endif + +xhtml: .docker/built + docker run --rm ${PATHS} -w /var/www -u ${CURRENT_UID}:${CURRENT_GID} php/doc-extensions + +php: .docker/built + docker run --rm ${PATHS} -w /var/www -u ${CURRENT_UID}:${CURRENT_GID} \ + -e FORMAT=php php/doc-extensions + +build: .docker/built + +.docker/built: .docker/Dockerfile + docker build \ + --build-arg UID=${CURRENT_UID} --build-arg GID=${CURRENT_GID} \ + .docker -t php/doc-extensions + touch .docker/built diff --git a/bookinfo.xml b/bookinfo.xml new file mode 100644 index 0000000..ba9a20e --- /dev/null +++ b/bookinfo.xml @@ -0,0 +1,30 @@ + + + + + + + This manual documents third-party PHP extensions: + extensions that are maintained outside the + php-src repository, and are typically distributed + via PECL or PIE. + + + It complements the main PHP manual, which documents the language + itself and the extensions bundled with PHP, available at + &url.php.docs;. + + + + + Copyright + + Copyright © 1997 - by the PHP Documentation Group. + This material may be distributed only subject to the terms and + conditions set forth in the Creative Commons Attribution 3.0 + License or later. The latest version is presently available at + &url.cc.by;. + + + + diff --git a/language-defs.ent b/language-defs.ent new file mode 100644 index 0000000..adb277a --- /dev/null +++ b/language-defs.ent @@ -0,0 +1,120 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +&Changelog;'> +Predefined Classes'> +Class synopsis'> +Enum synopsis'> +Predefined Constants'> +Constructor'> +Description'> +Encoding'> +Examples'> +Exceptions'> +Errors/Exceptions'> +&FAQ;'> +Installation'> +Introduction'> +Indices'> +Interface synopsis'> +Methods'> +MySQL Native Driver Only'> +Notes'> +Parameters'> +Options'> +Properties'> +Requirements'> +Resource Types'> +Runtime Configuration'> +Return Values'> +See Also'> +Installing/Configuring'> +Unicode'> +Usage'> diff --git a/language-snippets.ent b/language-snippets.ent new file mode 100644 index 0000000..6424e77 --- /dev/null +++ b/language-snippets.ent @@ -0,0 +1,3 @@ + + + diff --git a/manual.xml b/manual.xml new file mode 100644 index 0000000..2becd5c --- /dev/null +++ b/manual.xml @@ -0,0 +1,36 @@ + + + +%configure; + +%text-entities; + +%translation-defs; +%translation-snippets; +%translation-extensions; + +%language-defs; +%language-snippets; +%language-extensions; + +%base-entities; +%file-entities; + +]> + + + &ThirdPartyManual; + &bookinfo; + + + + &ThirdPartyExtensions; + &reference.example.book; + + + diff --git a/reference/example/book.xml b/reference/example/book.xml new file mode 100644 index 0000000..ec53c70 --- /dev/null +++ b/reference/example/book.xml @@ -0,0 +1,13 @@ + + + Example + Example + + + &reftitle.intro; + + Placeholder book serving as a template for third-party extension + documentation; it will be removed once real extensions are added. + + + From 1d53a10d79b38d1ae95daa6b94dcbe23f0b31a34 Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Tue, 4 Aug 2026 21:45:10 +0200 Subject: [PATCH 2/8] Use --with-base-lang --- .docker/Dockerfile | 2 +- manual.xml | 8 +++++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.docker/Dockerfile b/.docker/Dockerfile index 0a0e280..c87e65d 100644 --- a/.docker/Dockerfile +++ b/.docker/Dockerfile @@ -19,7 +19,7 @@ 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-lang=extensions --standalone && \ +php doc-base/configure.php --with-base-lang=extensions && \ exec php phd/render.php \ --docbook doc-base/.manual.xml \ --output=/var/www/extensions/output \ diff --git a/manual.xml b/manual.xml index 2becd5c..e6a9af6 100644 --- a/manual.xml +++ b/manual.xml @@ -2,6 +2,12 @@ + + %configure; @@ -20,7 +26,7 @@ ]> - + &ThirdPartyManual; &bookinfo; From af04bd117023c433b0256332cc14683b8ef8a3fe Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Wed, 5 Aug 2026 08:36:57 +0200 Subject: [PATCH 3/8] Process feedback --- .editorconfig | 2 +- .gitignore | 4 +--- Makefile | 10 +++++----- 3 files changed, 7 insertions(+), 9 deletions(-) diff --git a/.editorconfig b/.editorconfig index 5ab5087..02c4fef 100644 --- a/.editorconfig +++ b/.editorconfig @@ -9,4 +9,4 @@ indent_size = 1 indent_style = space end_of_line = lf insert_final_newline = true -trim_trailing_whitespace = false +trim_trailing_whitespace = true diff --git a/.gitignore b/.gitignore index 2da7b7f..3569f8c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,2 @@ -entities.*.xml -output -.docker/built +output/ temp/ diff --git a/Makefile b/Makefile index ca70aa3..546517e 100644 --- a/Makefile +++ b/Makefile @@ -18,17 +18,17 @@ ifneq ($(wildcard ../phd/LICENSE),) PATHS += -v ${PWD}/../phd:/var/www/phd endif -xhtml: .docker/built +xhtml: temp/.dockerbuilt docker run --rm ${PATHS} -w /var/www -u ${CURRENT_UID}:${CURRENT_GID} php/doc-extensions -php: .docker/built +php: temp/.dockerbuilt docker run --rm ${PATHS} -w /var/www -u ${CURRENT_UID}:${CURRENT_GID} \ -e FORMAT=php php/doc-extensions -build: .docker/built +build: temp/.dockerbuilt -.docker/built: .docker/Dockerfile +temp/.dockerbuilt: .docker/Dockerfile docker build \ --build-arg UID=${CURRENT_UID} --build-arg GID=${CURRENT_GID} \ .docker -t php/doc-extensions - touch .docker/built + touch temp/.dockerbuilt From 9782cce15f97efea7df0e489f4e0bee1795d307d Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Wed, 5 Aug 2026 11:36:55 +0200 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: Louis-Arnaud --- bookinfo.xml | 2 +- manual.xml | 2 +- reference/example/book.xml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/bookinfo.xml b/bookinfo.xml index ba9a20e..580f97b 100644 --- a/bookinfo.xml +++ b/bookinfo.xml @@ -1,5 +1,5 @@ - + diff --git a/manual.xml b/manual.xml index e6a9af6..a1ecb4b 100644 --- a/manual.xml +++ b/manual.xml @@ -26,7 +26,7 @@ ]> - + &ThirdPartyManual; &bookinfo; diff --git a/reference/example/book.xml b/reference/example/book.xml index ec53c70..20771e1 100644 --- a/reference/example/book.xml +++ b/reference/example/book.xml @@ -1,5 +1,5 @@ - + Example Example From fb67e03c6287e44ca3885cf4384feb6f5c138393 Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Wed, 5 Aug 2026 11:39:03 +0200 Subject: [PATCH 5/8] ensure temp directory exists before creating .dockerbuilt file --- Makefile | 2 +- bookinfo.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 546517e..558b9e1 100644 --- a/Makefile +++ b/Makefile @@ -31,4 +31,4 @@ temp/.dockerbuilt: .docker/Dockerfile docker build \ --build-arg UID=${CURRENT_UID} --build-arg GID=${CURRENT_GID} \ .docker -t php/doc-extensions - touch temp/.dockerbuilt + mkdir -p temp && touch temp/.dockerbuilt diff --git a/bookinfo.xml b/bookinfo.xml index 580f97b..e32ce2f 100644 --- a/bookinfo.xml +++ b/bookinfo.xml @@ -1,5 +1,5 @@ - + From 9bf13770725d56350f89c447ff17a61476704d8c Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Wed, 5 Aug 2026 11:47:38 +0200 Subject: [PATCH 6/8] add dev container and CI/CD workflows --- .devcontainer/build.sh | 46 ++++++++ .devcontainer/devcontainer.json | 58 +++++++++ .devcontainer/post-create.sh | 33 ++++++ .devcontainer/server-prepend.php | 15 +++ .github/ISSUE_TEMPLATE/bug-report.yml | 43 +++++++ .../documentation-improvement.yml | 40 +++++++ .github/dependabot.yml | 10 ++ .github/workflows/docbook-cs.yaml | 110 ++++++++++++++++++ .github/workflows/integrate.yaml | 66 +++++++++++ docbookcs.xml | 39 +++++++ 10 files changed, 460 insertions(+) create mode 100755 .devcontainer/build.sh create mode 100644 .devcontainer/devcontainer.json create mode 100755 .devcontainer/post-create.sh create mode 100644 .devcontainer/server-prepend.php create mode 100644 .github/ISSUE_TEMPLATE/bug-report.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation-improvement.yml create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/docbook-cs.yaml create mode 100644 .github/workflows/integrate.yaml create mode 100644 docbookcs.xml diff --git a/.devcontainer/build.sh b/.devcontainer/build.sh new file mode 100755 index 0000000..4648539 --- /dev/null +++ b/.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 "Build XHTML & serve" (or "Build PHP web & serve") + + View them: http://localhost:8080 + +EOF diff --git a/.devcontainer/server-prepend.php b/.devcontainer/server-prepend.php new file mode 100644 index 0000000..658e6f3 --- /dev/null +++ b/.devcontainer/server-prepend.php @@ -0,0 +1,15 @@ +/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 + env: + fail-fast: true + + - name: "Build documentation" + run: | + php doc-base/configure.php \ + --disable-libxml-check \ + --enable-xml-details \ + --redirect-stderr-to-stdout \ + --with-base-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 \ + --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/.github/workflows/integrate.yaml b/.github/workflows/integrate.yaml new file mode 100644 index 0000000..4bbc1a9 --- /dev/null +++ b/.github/workflows/integrate.yaml @@ -0,0 +1,66 @@ +# https://docs.github.com/en/actions + +name: "Integrate" + +on: + pull_request: null + push: + branches: + - "main" + +permissions: + contents: read + +jobs: + build: + name: "Build" + + runs-on: "ubuntu-latest" + + strategy: + matrix: + language: + - "extensions" + + steps: + - name: "Checkout php/doc-${{ matrix.language }}" + 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@v7" + with: + path: "${{ matrix.language }}" + repository: "php/doc-${{ matrix.language }}" + + - name: "Checkout php/doc-base" + uses: "actions/checkout@v7" + with: + path: "doc-base" + repository: "php/doc-base" + + - name: "Setup PHP" + uses: "shivammathur/setup-php@v2" + with: + php-version: "8.5" + extensions: "dom, libxml, simplexml" + env: + fail-fast: true + + - name: "Quality Assurance scripts" + run: | + php doc-base/scripts/qa/extensions.xml.php --check + php doc-base/scripts/qa/section-order.php + + - name: "Build documentation for ${{ matrix.language }}" + run: "php doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-base-lang=${{ matrix.language }}" + + - name: "Upload .manual.xml" + uses: actions/upload-artifact@v7 + with: + name: .manual.xml + path: doc-base/.manual.xml + include-hidden-files: true diff --git a/docbookcs.xml b/docbookcs.xml new file mode 100644 index 0000000..8c56e5c --- /dev/null +++ b/docbookcs.xml @@ -0,0 +1,39 @@ + + + + + extensions + doc-base + + + + + + + + + + + + . + + + + language-defs.ent + language-snippets.ent + entities/ + ../doc-base/entities/ + ../doc-base/temp/manual.ent + ../doc-base/temp/entities.ent + ../doc-base/temp/file-entities.ent + ../doc-base/temp/file-entities + + + + output/* + + + From 48ee1071c80e4bc1e46a5cff1b78243b6ed0ed2a Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Wed, 5 Aug 2026 11:52:42 +0200 Subject: [PATCH 7/8] remove QA scripts for the time being --- .github/workflows/integrate.yaml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/.github/workflows/integrate.yaml b/.github/workflows/integrate.yaml index 4bbc1a9..5225b49 100644 --- a/.github/workflows/integrate.yaml +++ b/.github/workflows/integrate.yaml @@ -50,11 +50,6 @@ jobs: env: fail-fast: true - - name: "Quality Assurance scripts" - run: | - php doc-base/scripts/qa/extensions.xml.php --check - php doc-base/scripts/qa/section-order.php - - name: "Build documentation for ${{ matrix.language }}" run: "php doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-base-lang=${{ matrix.language }}" From de5d2103b607e955aa2b92907318f95539524d87 Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Wed, 5 Aug 2026 12:52:56 +0200 Subject: [PATCH 8/8] remove fallback from CI/CD --- .github/workflows/integrate.yaml | 7 ------- 1 file changed, 7 deletions(-) diff --git a/.github/workflows/integrate.yaml b/.github/workflows/integrate.yaml index 5225b49..733ec28 100644 --- a/.github/workflows/integrate.yaml +++ b/.github/workflows/integrate.yaml @@ -29,13 +29,6 @@ jobs: path: "${{ matrix.language }}" repository: "php/doc-${{ matrix.language }}" - - name: "Checkout php/doc-en as fallback" - if: "matrix.language != 'en'" - uses: "actions/checkout@v7" - with: - path: "${{ matrix.language }}" - repository: "php/doc-${{ matrix.language }}" - - name: "Checkout php/doc-base" uses: "actions/checkout@v7" with: