From 281b833eef00a09e273486453bae2ba94533241e Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Sat, 13 Jun 2026 00:59:38 +0300 Subject: [PATCH 01/11] returntypewillchange.xml Add warning about future strict return type enforcement Should we not explicitly mention that internal methods will strictly enforce return types in future PHP versions? Currently, the documentation might give developers a false sense of security, making it look like `#[ReturnTypeWillChange]` is a permanent fix. In reality, it only works during the tentative phase. Once PHP 9.0 drops, any remaining signature mismatches in child classes will cause a fatal error, as far as I understand --- .../predefined/attributes/returntypewillchange.xml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml index 12f7f83961c6..7e3c609874c3 100644 --- a/language/predefined/attributes/returntypewillchange.xml +++ b/language/predefined/attributes/returntypewillchange.xml @@ -16,6 +16,17 @@ a #[\ReturnTypeWillChange] attribute can be added to silence the deprecation notice. + + + + The ReturnTypeWillChange attribute suppresses + deprecation warnings during the tentative return type phase only. + Any remaining signatures mismatches will trigger an E_COMPILE_ERROR once internal methods + transition to standard strict return types. This breaking change is scheduled for PHP 9.0.0, + at which point a fatal error is raised and this attribute will no longer have any effect. + + +
From ae0308649e1d25e07edb30195da7d3e133f883cd Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Sat, 13 Jun 2026 01:06:37 +0300 Subject: [PATCH 02/11] returntypewillchange.xml Remove trailing whitespace --- language/predefined/attributes/returntypewillchange.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml index 7e3c609874c3..f4c24773f0a0 100644 --- a/language/predefined/attributes/returntypewillchange.xml +++ b/language/predefined/attributes/returntypewillchange.xml @@ -19,10 +19,10 @@ - The ReturnTypeWillChange attribute suppresses + The ReturnTypeWillChange attribute suppresses deprecation warnings during the tentative return type phase only. - Any remaining signatures mismatches will trigger an E_COMPILE_ERROR once internal methods - transition to standard strict return types. This breaking change is scheduled for PHP 9.0.0, + Any remaining signatures mismatches will trigger an E_COMPILE_ERROR once internal methods + transition to standard strict return types. This breaking change is scheduled for PHP 9.0.0, at which point a fatal error is raised and this attribute will no longer have any effect. From 37b2fdaedc7a6384ade243535961578287f13814 Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Sat, 13 Jun 2026 03:55:03 +0300 Subject: [PATCH 03/11] returntypewillchange.xml Remove whitespace --- language/predefined/attributes/returntypewillchange.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml index f4c24773f0a0..d4d18dc8f5f6 100644 --- a/language/predefined/attributes/returntypewillchange.xml +++ b/language/predefined/attributes/returntypewillchange.xml @@ -24,9 +24,9 @@ Any remaining signatures mismatches will trigger an E_COMPILE_ERROR once internal methods transition to standard strict return types. This breaking change is scheduled for PHP 9.0.0, at which point a fatal error is raised and this attribute will no longer have any effect. - - - + + +
From 775553596ff999ac2d1b607e15e2321710622a6d Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Sun, 14 Jun 2026 03:53:16 +0300 Subject: [PATCH 04/11] returntypewillchange.xml Change the wording --- language/predefined/attributes/returntypewillchange.xml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml index d4d18dc8f5f6..01cc79b36137 100644 --- a/language/predefined/attributes/returntypewillchange.xml +++ b/language/predefined/attributes/returntypewillchange.xml @@ -11,6 +11,9 @@ Most non-final internal methods now require overriding methods to declare a compatible return type, otherwise a deprecated notice is emitted during inheritance validation. + This introduces a tentative return type phase: + the engine emits a deprecation notice instead of a fatal error when return + types are incompatible, before they become enforced in a future version. In case the return type cannot be declared for an overriding method due to PHP cross-version compatibility concerns, a #[\ReturnTypeWillChange] attribute can be added to silence @@ -21,9 +24,9 @@ The ReturnTypeWillChange attribute suppresses deprecation warnings during the tentative return type phase only. - Any remaining signatures mismatches will trigger an E_COMPILE_ERROR once internal methods - transition to standard strict return types. This breaking change is scheduled for PHP 9.0.0, - at which point a fatal error is raised and this attribute will no longer have any effect. + It has no effect when overriding methods defined in user-defined classes. + Once internal methods adopt strict types, mismatches in overriding method + signatures will cause a fatal error and this attribute will no longer have any effect. From 314b3e68c182e83e3683c2b7ee1ba8426a45d08e Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Sun, 14 Jun 2026 04:00:58 +0300 Subject: [PATCH 05/11] Update returntypewillchange.xml --- language/predefined/attributes/returntypewillchange.xml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml index 01cc79b36137..0e1b1609a518 100644 --- a/language/predefined/attributes/returntypewillchange.xml +++ b/language/predefined/attributes/returntypewillchange.xml @@ -10,8 +10,7 @@ Most non-final internal methods now require overriding methods to declare a compatible return type, otherwise a deprecated notice is emitted during - inheritance validation. - This introduces a tentative return type phase: + inheritance validation. This introduces a tentative return type phase: the engine emits a deprecation notice instead of a fatal error when return types are incompatible, before they become enforced in a future version. In case the return type cannot be declared for an overriding method due to From 2a7cdf8484a4d92a65d4c02196416ada903be5fd Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Sun, 14 Jun 2026 05:06:41 +0300 Subject: [PATCH 06/11] Update returntypewillchange.xml From 525503c8380fd2ad96ac33bfec519f61778da661 Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Sun, 14 Jun 2026 14:32:46 +0300 Subject: [PATCH 07/11] Update language/predefined/attributes/returntypewillchange.xml Co-authored-by: Jordi Kroon --- language/predefined/attributes/returntypewillchange.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml index 0e1b1609a518..50707b40f7e7 100644 --- a/language/predefined/attributes/returntypewillchange.xml +++ b/language/predefined/attributes/returntypewillchange.xml @@ -7,7 +7,7 @@
&reftitle.intro; - + Most non-final internal methods now require overriding methods to declare a compatible return type, otherwise a deprecated notice is emitted during inheritance validation. This introduces a tentative return type phase: From 6b0a85ea6cf84f2752d316ee556f0a821aec0886 Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Sun, 14 Jun 2026 14:32:58 +0300 Subject: [PATCH 08/11] Update language/predefined/attributes/returntypewillchange.xml Co-authored-by: Jordi Kroon --- language/predefined/attributes/returntypewillchange.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml index 50707b40f7e7..f5f54acea897 100644 --- a/language/predefined/attributes/returntypewillchange.xml +++ b/language/predefined/attributes/returntypewillchange.xml @@ -17,7 +17,7 @@ PHP cross-version compatibility concerns, a #[\ReturnTypeWillChange] attribute can be added to silence the deprecation notice. - + From 95179164dcb4ba771d1d8533a02d28548bd5ee32 Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Sat, 13 Jun 2026 22:43:30 +0200 Subject: [PATCH 09/11] Add docbook-cs (#5524) --- .github/workflows/check-whitespace.yml | 29 ------- .github/workflows/docbook-cs.yaml | 107 +++++++++++++++++++++++++ docbookcs.xml | 37 +++++++++ 3 files changed, 144 insertions(+), 29 deletions(-) delete mode 100644 .github/workflows/check-whitespace.yml create mode 100644 .github/workflows/docbook-cs.yaml create mode 100644 docbookcs.xml 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 "check-whitespace@example.com" - - 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 @@ + + + + + en + doc-base + + + + + + + + + + + . + + + + contributors.ent + extensions.ent + language-defs.ent + language-snippets.ent + ../doc-base/entities/ + ../doc-base/temp/file-entities.ent + ../doc-base/temp/file-entities + + + + output/* + + + From 72301b192b36912e1a6caaf5922160c122ccdc43 Mon Sep 17 00:00:00 2001 From: Mikhail Alferov Date: Sun, 14 Jun 2026 11:22:02 +0300 Subject: [PATCH 10/11] reflection: Delete outdated paragraph in hasreturntype.xml (#5610) --- .../reflectionfunctionabstract/hasreturntype.xml | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/reference/reflection/reflectionfunctionabstract/hasreturntype.xml b/reference/reflection/reflectionfunctionabstract/hasreturntype.xml index 42fc2502da54..40846a250b97 100644 --- a/reference/reflection/reflectionfunctionabstract/hasreturntype.xml +++ b/reference/reflection/reflectionfunctionabstract/hasreturntype.xml @@ -38,7 +38,8 @@ - - This is because many internal functions do not have types specified for their - parameters or return values. It is therefore best to avoid using this - method on built-in functions. - From a0f81eed19cd11ab227db1a2a183a9de7a282a21 Mon Sep 17 00:00:00 2001 From: KentarouTakeda <4785040+KentarouTakeda@users.noreply.github.com> Date: Sun, 14 Jun 2026 17:23:05 +0900 Subject: [PATCH 11/11] pcntl: Fix duplicate documentation for pcntl_getqos_class and pcntl_setqos_class (#5609) * Fix duplicate documentation for pcntl_getqos_class and pcntl_setqos_class These functions were each documented in two files sharing the same xml:id. The build normalizes _ to - in file-entity names, so the hyphen-named files (#5350) collided with the underscore-named ones (#5506) and were silently dropped. Merge both versions into the hyphen-named files and remove the underscore-named ones. * Address review: use exceptionname for Error and simpara for parameters Mark the thrown Error with , use for the qos_class description, and drop the wrapper around its . --- .../pcntl/functions/pcntl-getqos-class.xml | 23 ++- .../pcntl/functions/pcntl-setqos-class.xml | 86 +++++++++-- .../pcntl/functions/pcntl_getqos_class.xml | 71 --------- .../pcntl/functions/pcntl_setqos_class.xml | 137 ------------------ 4 files changed, 89 insertions(+), 228 deletions(-) delete mode 100644 reference/pcntl/functions/pcntl_getqos_class.xml delete mode 100644 reference/pcntl/functions/pcntl_setqos_class.xml diff --git a/reference/pcntl/functions/pcntl-getqos-class.xml b/reference/pcntl/functions/pcntl-getqos-class.xml index 430a54f5d030..8ac56ebc737c 100644 --- a/reference/pcntl/functions/pcntl-getqos-class.xml +++ b/reference/pcntl/functions/pcntl-getqos-class.xml @@ -2,7 +2,7 @@ pcntl_getqos_class - Get the current Quality of Service class of the process + Get the QoS class of the current thread @@ -12,10 +12,12 @@ - Returns the current Quality of Service (QoS) class of the calling process. - This function is only available on macOS, which uses QoS classes to - manage energy efficiency and performance. + Retrieves the Quality of Service (QoS) class of the + current thread. + + This function is only available on Apple platforms. + @@ -26,8 +28,16 @@ &reftitle.returnvalues; - Returns a Pcntl\QosClass enum value representing - the current QoS class. + Returns the current QoS class as a + Pcntl\QosClass. + + + + + &reftitle.errors; + + Throws an Error if the underlying call to + pthread_get_qos_class_np() fails. @@ -35,6 +45,7 @@ &reftitle.seealso; pcntl_setqos_class + Pcntl\QosClass diff --git a/reference/pcntl/functions/pcntl-setqos-class.xml b/reference/pcntl/functions/pcntl-setqos-class.xml index 698d0d231f19..f314f15199a9 100644 --- a/reference/pcntl/functions/pcntl-setqos-class.xml +++ b/reference/pcntl/functions/pcntl-setqos-class.xml @@ -2,19 +2,18 @@ pcntl_setqos_class - Set the Quality of Service class of the process + Set the QoS class of the current thread &reftitle.description; voidpcntl_setqos_class - Pcntl\QosClassqos_classPcntl\QosClass::Default + Pcntl\QosClassqos_classPcntl\QosClass::Default - Sets the Quality of Service (QoS) class of the calling process. - This function is only available on macOS, which uses QoS classes to - manage energy efficiency and performance. + Sets the Quality of Service (QoS) class of the current + thread. @@ -25,19 +24,69 @@ qos_class - The QoS class to set. Must be one of the - Pcntl\QosClass enum values: + The Quality of Service class to assign to the current thread. The + operating system uses this as a hint to schedule CPU time, I/O priority, + and energy usage, with higher classes preempting lower ones. See + Pcntl\QosClass for the available cases. - - Pcntl\QosClass::UserInteractive - Pcntl\QosClass::UserInitiated - Pcntl\QosClass::Default - Pcntl\QosClass::Utility - Pcntl\QosClass::Background - + + + Pcntl\QosClass::UserInteractive + + + Highest priority. Intended for work that directly drives a user + interface and must complete virtually instantly to avoid perceived + delay, such as event handling or drawing. + + + + + Pcntl\QosClass::UserInitiated + + + High priority, just below UserInteractive. + Intended for work the user has explicitly initiated and is actively + waiting on, expected to complete within a few seconds. + + + + + Pcntl\QosClass::Default + + + Standard priority, used when no more specific class applies. Runs + after higher-priority work but ahead of Utility + and Background. + + + + + Pcntl\QosClass::Utility + + + Lower priority, intended for long-running work the user is aware of + but not actively waiting on, such as downloads, imports, or bulk + computation. Scheduled in an energy-efficient manner. + + + + + Pcntl\QosClass::Background + + + Lowest priority, intended for work the user is not aware of, such as + prefetching, indexing, or maintenance. Heavily optimized for energy + efficiency and may be deferred when the system is under load. + + + + + + This function is only available on Apple platforms. + @@ -47,10 +96,19 @@ + + &reftitle.errors; + + Throws an Error if the underlying call to + pthread_set_qos_class_self_np() fails. + + + &reftitle.seealso; pcntl_getqos_class + Pcntl\QosClass diff --git a/reference/pcntl/functions/pcntl_getqos_class.xml b/reference/pcntl/functions/pcntl_getqos_class.xml deleted file mode 100644 index 83d16d1424b6..000000000000 --- a/reference/pcntl/functions/pcntl_getqos_class.xml +++ /dev/null @@ -1,71 +0,0 @@ - - - - - pcntl_getqos_class - Get the QoS class of the current thread - - - - &reftitle.description; - - Pcntl\QosClasspcntl_getqos_class - - - - Retrieve the QoS class. - - - This function is only available on Apple platforms. - - - - - &reftitle.parameters; - &no.function.parameters; - - - - &reftitle.returnvalues; - - Returns the Pcntl\QosClass. - - - - - &reftitle.errors; - - Throws an Error if the underlying call to - pthread_get_qos_class_np() fails. - - - - - &reftitle.seealso; - - pcntl_setqos_class - Pcntl\QosClass - - - - - diff --git a/reference/pcntl/functions/pcntl_setqos_class.xml b/reference/pcntl/functions/pcntl_setqos_class.xml deleted file mode 100644 index 113272c0305a..000000000000 --- a/reference/pcntl/functions/pcntl_setqos_class.xml +++ /dev/null @@ -1,137 +0,0 @@ - - - - - pcntl_setqos_class - Set the QoS class of the current thread - - - - &reftitle.description; - - voidpcntl_setqos_class - Pcntl\QosClassqos_classPcntl\QosClass::Default - - - Set the QoS class. - - - - - &reftitle.parameters; - - - qos_class - - - The Quality of Service class to assign to the current thread. The - operating system uses this as a hint to schedule CPU time, I/O priority, - and energy usage, with higher classes preempting lower ones. See - Pcntl\QosClass for the available cases. - - - - - Pcntl\QosClass::UserInteractive - - - Highest priority. Intended for work that directly drives a user - interface and must complete virtually instantly to avoid perceived - delay, such as event handling or drawing. - - - - - Pcntl\QosClass::UserInitiated - - - High priority, just below UserInteractive. - Intended for work the user has explicitly initiated and is actively - waiting on, expected to complete within a few seconds. - - - - - Pcntl\QosClass::Default - - - Standard priority, used when no more specific class applies. Runs - after higher-priority work but ahead of Utility - and Background. - - - - - Pcntl\QosClass::Utility - - - Lower priority, intended for long-running work the user is aware of - but not actively waiting on, such as downloads, imports, or bulk - computation. Scheduled in an energy-efficient manner. - - - - - Pcntl\QosClass::Background - - - Lowest priority, intended for work the user is not aware of, such as - prefetching, indexing, or maintenance. Heavily optimized for energy - efficiency and may be deferred when the system is under load. - - - - - - - - - - This function is only available on Apple platforms. - - - - - &reftitle.returnvalues; - - &return.void; - - - - - &reftitle.errors; - - Throws an Error if the underlying call to - pthread_set_qos_class_self_np() fails. - - - - - &reftitle.seealso; - - pcntl_getqos_class - Pcntl\QosClass - - - - -