[DOC-CVS] [doc-en] master: ext/pcre: document variable-length lookbehind and longer subpattern names (PHP 8.4) (#5739)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-08-17T19:04:37+02:00

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

ext/pcre: document variable-length lookbehind and longer subpattern names (PHP 8.4) (#5739)

* ext/pcre: Document variable-length lookbehind and 128-char subpattern names (PCRE2 10.44)

Document variable-length lookbehind as the current behaviour and move the
fixed-length restriction below, as historical information for versions
prior to PHP 8.4.0.

---------

Co-authored-by: Jordi Kroon <[email protected]>

Changed paths:
  M  reference/pcre/pattern.syntax.xml


Diff:

diff --git a/reference/pcre/pattern.syntax.xml b/reference/pcre/pattern.syntax.xml
index f1315e2a0bab..9e832051bc79 100644
--- a/reference/pcre/pattern.syntax.xml
+++ b/reference/pcre/pattern.syntax.xml
@@ -1510,6 +1510,10 @@
    also by name. There are two alternative syntaxes
    <literal>(?&lt;name&gt;pattern)</literal> and <literal>(?'name'pattern)</literal>.
   </para>
+  <simpara>
+   As of PHP 8.4.0, which bundles PCRE2 10.44, the maximum length of a
+   subpattern name is 128 characters; previously it was 32 characters.
+  </simpara>
 
   <para>
    Sometimes it is necessary to have multiple matching, but alternating
@@ -1874,37 +1878,24 @@
    when the next three characters are "bar". A lookbehind
    assertion is needed to achieve this effect.
   </para>
-  <para>
+  <simpara>
    <emphasis>Lookbehind</emphasis> assertions start with (?&lt;= for positive assertions
    and (?&lt;! for negative assertions. For example,
 
    <literal>(?&lt;!foo)bar</literal>
 
    does find an occurrence of "bar" that is not preceded by
-   "foo". The contents of a lookbehind assertion are restricted
-   such that all the strings it matches must have a fixed
-   length. However, if there are several alternatives, they do
-   not all have to have the same fixed length. Thus
-
-   <literal>(?&lt;=bullock|donkey)</literal>
-
-   is permitted, but
+   "foo". A lookbehind assertion may match strings of variable
+   length, up to an implementation-defined maximum length.
+   Alternatives of differing lengths, such as
 
    <literal>(?&lt;!dogs?|cats?)</literal>
 
-   causes an error at compile time. Branches that match different
-   length strings are permitted only at the top level of
-   a lookbehind assertion. This is an extension compared with
-   Perl 5.005, which requires all branches to match the same
-   length of string. An assertion such as
+   and top-level branches that can match more than one length, such as
 
    <literal>(?&lt;=ab(c|de))</literal>
 
-   is not permitted, because its single top-level branch can
-   match two different lengths, but it is acceptable if rewritten
-   to use two top-level branches:
-
-   <literal>(?&lt;=abc|abde)</literal>
+   are permitted.
 
    The implementation of lookbehind assertions is, for each
    alternative, to temporarily move the current position back
@@ -1914,7 +1905,33 @@
    once-only subpatterns can be particularly useful for matching
    at the ends of strings; an example is given at the end
    of the section on once-only subpatterns.
-  </para>
+  </simpara>
+  <simpara>
+   Prior to PHP 8.4.0, which bundles PCRE2 10.44, the contents of a lookbehind
+   assertion were restricted such that all the strings it matched had to have a
+   fixed length. If there were several alternatives, they did not all have to
+   have the same fixed length, thus
+
+   <literal>(?&lt;=bullock|donkey)</literal>
+
+   was permitted, but
+
+   <literal>(?&lt;!dogs?|cats?)</literal>
+
+   caused an error at compile time. Branches that matched different
+   length strings were permitted only at the top level of
+   a lookbehind assertion. This was an extension compared with
+   Perl 5.005, which required all branches to match the same
+   length of string. An assertion such as
+
+   <literal>(?&lt;=ab(c|de))</literal>
+
+   was not permitted, because its single top-level branch could
+   match two different lengths, but it was acceptable if rewritten
+   to use two top-level branches:
+
+   <literal>(?&lt;=abc|abde)</literal>
+  </simpara>
   <para>
    Several assertions (of any sort) may occur in succession.
    For example,