[DOC-CVS] [doc-en] master: PCRE: Tidy up and clean-up some outdated things (#4875)

Author: Josh (joshtrichards)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-27T16:13:23+02:00

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

PCRE: Tidy up and clean-up some outdated things  (#4875)

* PCRE2: Clean-up "Perl Differences" docs

Removed the VERY outdated list of differences (it's from <PCRE1 4.0!). Replaced it with a link to the current official PCRE2 documentation on the topic. 

Used a link since the old content was just a verbatim snapshot of the same docs (albeit an older version). It wasn't adding any value being copied directly here (and would quickly just get out of date).

Also, added a note about the relevance of the PCRE2 library version.

* Revise PCRE extension preface for clarity

- Add actual introductory paragraph
- Drop syntax details which are already thoroughly documented elsewhere (and already linked)
- Clarify expression caching
- Update size limitations link point at PCRE2 one
- Drop stale final paragraph that didn't belong and is redundant

* Revise PCRE extension installation instructions

- Remove the outdated configuration option; replace it with the supported option
- Tidy up the opening paragraph(s)
- Update the required PCRE2 external version to match the config implementation
- Tidy up JIT paragraph
- Tidy up "changes" paragraph; replace changelog link to point at the one for PCRE2 rather than the deprecated/unmaintained PCRE1 one
- Add 8.3.0-8.5.0 entries to bundled PCRE library history

* Fix formatting in pattern.differences.xml

* Fix formatting of warning message in book.xml

* Fix build failure and factual errors in the PCRE clean-up

pattern.differences.xml did not build: the <para> was left unclosed. The
file also used xlink:href without declaring the xlink namespace on
<article>, which every other file in reference/pcre/ does.

configure.xml claimed PHP 8.5.0 bundles PCRE2 10.46. The 10.45 and 10.46
upgrades were both reverted in php-src before 8.5.0 was released, so 8.5
still bundles 10.44, the same version as 8.4.0; the row is dropped since
the table records upgrades. The pre-existing 8.1.0 row was also wrong:
8.1.0 shipped 10.37, 10.39 arrived in 8.1.1. The external library option
is noted as unavailable on Windows, where config.w32 has no such option
and the bundled library is always used.

book.xml described cache eviction as removing the oldest entry under a
FIFO policy. php_pcre.c discards a batch of PCRE_CACHE_SIZE / 8 entries
and skips any entry still referenced, so the wording is relaxed to match.
Also fixes the "oneones" typo and restores the link to Pattern Modifiers,
which the preface no longer pointed to.

The note that a delimiter cannot be a NUL byte was dropped from book.xml
without an equivalent elsewhere; it is restored in pattern.syntax.xml,
where delimiters are documented.

Paragraphs touched here are inline-only and are converted to <simpara>
as required by the DocBook style check. This also fixes the rendered
output: PhD wraps note content in <p>, so a <para> inside a <note>
produced a <p> nested in a <p>.

---------

Co-authored-by: Louis-Arnaud <[email protected]>

Changed paths:
  M  reference/pcre/book.xml
  M  reference/pcre/configure.xml
  M  reference/pcre/pattern.differences.xml
  M  reference/pcre/pattern.syntax.xml


Diff:

diff --git a/reference/pcre/book.xml b/reference/pcre/book.xml
index 808f92d13c2f..94f75617d33d 100644
--- a/reference/pcre/book.xml
+++ b/reference/pcre/book.xml
@@ -4,46 +4,40 @@
 <book xml:id="book.pcre" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="interactive">
  <?phpdoc extension-membership="core" ?>
  <title>Regular Expressions (Perl-Compatible)</title>
- <titleabbrev>PCRE</titleabbrev>   
+ <titleabbrev>PCRE</titleabbrev>
 
  <preface xml:id="intro.pcre">
   &reftitle.intro;
-  <para>
-   The syntax for patterns used in these functions closely resembles
-   Perl. The expression must be enclosed in the delimiters, a
-   forward slash (/), for example.  Delimiters can be any 
-   non-alphanumeric, non-whitespace ASCII character except the backslash (\) and the
-   null byte. If the delimiter character has to be used in the 
-   expression itself, it needs to be escaped by backslash.
-   Perl-style (), {}, [], and &lt;&gt; matching delimiters may also be used.
+  <simpara>
+   This extension integrates regular expression pattern matching support into
+   PHP. It is based on the free and open-source
+   <link xlink:href="&url.pcre2.website;">PCRE2 library</link>.
+   This library implements regular expression pattern matching
+   using syntax and semantics compatible with Perl,
+   with a few
+   <link xlink:href="&url.pcre2.perlcompat;">documented differences</link>.
    See <link linkend="reference.pcre.pattern.syntax">Pattern Syntax</link>
-   for detailed explanation.
-  </para>
-  <para>
-   The ending delimiter may be followed by various modifiers that
-   affect the matching. 
-   See <link linkend="reference.pcre.pattern.modifiers">Pattern
-    Modifiers</link>.
-  </para>
+   and <link linkend="reference.pcre.pattern.modifiers">Pattern Modifiers</link>
+   for a detailed explanation.
+  </simpara>
+  <simpara>
+   To improve performance, the extension caches compiled regular expressions.
+   Each thread has its own dedicated cache, capable of holding up to 4096
+   expressions.
+  </simpara>
   <note>
-   <para>
-    This extension maintains a global per-thread cache of compiled regular
-    expressions (up to 4096).
-   </para>
+   <simpara>
+    When the cache is full, a batch of the oldest entries that are not
+    currently in use is discarded to make room for new ones. The cache size
+    is not configurable.
+   </simpara>
   </note>
   <warning>
-   <para>
-    You should be aware of some limitations of PCRE. Read <link
-     xlink:href="&url.pcre.man;">&url.pcre.man;</link> for more info.
-   </para>
+   <simpara>
+    PCRE2 imposes <link xlink:href="&url.pcre2.limits;">size and other
+    limits</link> that may be relevant in some cases.
+   </simpara>
   </warning>
-  <!-- FIXME: Check what Perl version implementation corresponds -->
-  <para>
-   The PCRE library is a set of functions that implement regular
-   expression pattern matching using the same syntax and semantics
-   as Perl 5, with just a few differences (see below).  The current
-   implementation corresponds to Perl 5.005.
-  </para>
  </preface>
 
  &reference.pcre.setup;
diff --git a/reference/pcre/configure.xml b/reference/pcre/configure.xml
index 5ce103488977..d44565f9d8ae 100644
--- a/reference/pcre/configure.xml
+++ b/reference/pcre/configure.xml
@@ -2,29 +2,29 @@
 <!-- $Revision$ -->
 <section xml:id="pcre.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  &reftitle.install;
- <para>
-  The PCRE extension is a core PHP extension, so it is always enabled.
-  By default, this extension is compiled using the bundled PCRE
-  library. Alternatively, an external PCRE library can be used by
-  passing in the <option role="configure">--with-pcre-regex=DIR</option>
-  configuration option where <literal>DIR</literal> is the location of
-  PCRE's include and library files. It is recommended to use PCRE 8.10 or newer;
-  as of PHP 7.3.0, PCRE2 is required.
- </para>
- <para>
-  PCRE's just-in-time compilation is supported by default, which
-  can be disabled with the <option role="configure">--without-pcre-jit</option>
-  configuration option as of PHP 7.0.12.
- </para>
+ <simpara>
+  The PCRE extension is a core PHP extension and is always enabled.
+ </simpara>
+ <simpara>
+  By default, the extension uses a bundled version of the PCRE2 library.
+  On non-Windows systems, an external PCRE2 library can be used instead with
+  the <option role="configure">--with-external-pcre</option> configuration
+  option. The minimum supported version is 10.30. Windows builds always use
+  the bundled library.
+ </simpara>
+ <simpara>
+  PCRE2's just-in-time (JIT) compilation is enabled by default.
+  It can be disabled with the <option role="configure">--without-pcre-jit</option>
+  configuration option.
+ </simpara>
  &windows.builtin;
- <para>
-  PCRE is an active project and as it changes so does the PHP
+ <simpara>
+  PCRE2 is an active project, and as it changes, so does the PHP
   functionality that relies upon it. It is possible that certain parts
-  of the PHP documentation is outdated, in that it may not cover the
-  newest features that PCRE provides. For a list of changes, see the
-  <link xlink:href="&url.pcre.changelog;">PCRE library changelog</link>
-  and also the following bundled PCRE history:
- </para>
+  of the PHP documentation are outdated. For a list of changes, see the
+  <link xlink:href="&url.pcre2.changelog;">PCRE2 library changelog</link>.
+  The upgrade history of the bundled library is listed below:
+ </simpara>
  <para>
   <table>
    <title>Upgrade history of the bundled PCRE library</title>
@@ -37,16 +37,31 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>10.44</entry>
+      <entry></entry>
+     </row>
+     <row>
+      <entry>8.3.0</entry>
+      <entry>10.42</entry>
+      <entry></entry>
+     </row>
      <row>
       <entry>8.2.0</entry>
       <entry>10.40</entry>
       <entry></entry>
      </row>
      <row>
-      <entry>8.1.0</entry>
+      <entry>8.1.1</entry>
       <entry>10.39</entry>
       <entry></entry>
      </row>
+     <row>
+      <entry>8.1.0</entry>
+      <entry>10.37</entry>
+      <entry></entry>
+     </row>
      <row>
       <entry>7.4.12, 8.0.0</entry>
       <entry>10.35</entry>
diff --git a/reference/pcre/pattern.differences.xml b/reference/pcre/pattern.differences.xml
index 290c3d849444..90d48e0c1f72 100644
--- a/reference/pcre/pattern.differences.xml
+++ b/reference/pcre/pattern.differences.xml
@@ -1,137 +1,15 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
 <!-- splitted from ./en/functions/pcre.xml, last change in rev 1.2 -->
-<article xml:id="reference.pcre.pattern.differences" xmlns="http://docbook.org/ns/docbook">
+<article xml:id="reference.pcre.pattern.differences" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Perl Differences</title>
  <titleabbrev>Differences From Perl</titleabbrev>
- <para>
-  The differences described here are with respect to Perl 5.005.
-  <orderedlist>
-   <listitem>
-    <simpara>
-     By default, a whitespace character is any character  that
-     the C library function isspace() recognizes, though it is
-     possible to compile PCRE  with alternative character type
-     tables. Normally isspace() matches space, formfeed, newline,
-     carriage return, horizontal tab, and vertical tab. Perl 5 no
-     longer  includes vertical tab in its set of whitespace characters.
-     The \v escape that was in the Perl documentation for
-     a long time was never in fact recognized. However, the character
-     itself was treated as whitespace at least up to 5.002.
-     In 5.004 and 5.005 it does not match \s.
-    </simpara>
-   </listitem>
-   <listitem>
-    <simpara>
-     PCRE does not allow repeat quantifiers on lookahead
-     assertions. Perl permits them, but they do not mean what you
-     might think. For example, (?!a){3} does not assert that  the
-     next three characters are not "a". It just asserts that the
-     next character is not "a" three times.
-    </simpara>
-   </listitem>
-   <listitem>
-    <simpara>
-     Capturing subpatterns that occur inside negative
-     lookahead assertions are counted, but their entries in the
-     offsets vector are never set. Perl sets its numerical
-     variables from any such patterns that are matched before the
-     assertion fails to match something (thereby succeeding), but
-     only  if  the negative lookahead assertion contains just one
-     branch.
-    </simpara>
-   </listitem>
-   <listitem>
-    <simpara>
-     Though binary zero characters are supported in  the  subject  string,
-     they are not allowed in a pattern string because it is passed as a
-     normal C string, terminated  by zero. The escape sequence "\x00" can
-     be used in the pattern to represent a binary zero.
-    </simpara>
-    </listitem>
-    <listitem>
-    <simpara>
-     The following Perl escape sequences  are  not  supported:
-     \l,  \u,  \L,  \U. In fact these are implemented by
-     Perl's general string-handling and are not part of its
-     pattern matching engine.
-    </simpara>
-    </listitem>
-    <listitem>
-    <simpara>
-     The Perl \G assertion is  not  supported  as  it  is  not
-     relevant to single pattern matches.
-    </simpara>
-    </listitem>
-    <listitem>
-    <simpara>
-     Fairly obviously, PCRE does not support the (?{code}) and (??{code})
-     construction. However, there is support for recursive  patterns.
-    </simpara>
-    </listitem>
-    <listitem>
-    <simpara>
-     There are at the time of writing some  oddities  in  Perl
-     5.005_02  concerned  with  the  settings of captured strings
-     when part of a pattern is repeated.  For  example,  matching
-     "aba"  against the pattern /^(a(b)?)+$/ sets $2 to the value
-     "b", but matching "aabbaa" against /^(aa(bb)?)+$/ leaves  $2
-     unset.    However,    if   the   pattern   is   changed   to
-     /^(aa(b(b))?)+$/ then $2 (and $3) get set.
-     In Perl 5.004 $2 is set in both cases, and that is also &true;
-     of PCRE. If in the future Perl changes to a consistent state
-     that is different, PCRE may change to follow.
-    </simpara>
-    </listitem>
-    <listitem>
-    <simpara>
-     Another as yet unresolved discrepancy  is  that  in  Perl
-     5.005_02  the  pattern /^(a)?(?(1)a|b)+$/ matches the string
-     "a", whereas in PCRE it does not.  However, in both Perl and
-     PCRE /^(a)?a/ matched against "a" leaves $1 unset.
-    </simpara>
-    </listitem>
-    <listitem>
-    <para>
-     PCRE  provides  some  extensions  to  the  Perl  regular
-     expression facilities:
-      <orderedlist>
-       <listitem>
-        <simpara>
-         Although lookbehind assertions must match  fixed  length
-         strings,  each  alternative branch of a lookbehind assertion
-         can match a different length of string. Perl 5.005  requires
-         them all to have the same length.
-       </simpara>
-      </listitem>
-      <listitem>
-       <simpara>
-        If <link linkend="reference.pcre.pattern.modifiers">PCRE_DOLLAR_ENDONLY</link>
-        is set and <link linkend="reference.pcre.pattern.modifiers">PCRE_MULTILINE</link> is
-        not set, the $ meta-character matches only at the very end of the
-        string.
-       </simpara>
-      </listitem>
-      <listitem>
-       <simpara>
-        If <link linkend="reference.pcre.pattern.modifiers">PCRE_EXTRA</link> is
-        set, a backslash followed by a letter with no special meaning is
-        faulted.
-       </simpara>
-      </listitem>
-      <listitem>
-       <simpara>
-        If <link linkend="reference.pcre.pattern.modifiers">PCRE_UNGREEDY</link> is
-        set, the greediness of the repetition  quantifiers  is inverted,
-        that is, by default they are not greedy, but if followed by a
-        question mark they are.
-       </simpara>
-      </listitem>
-     </orderedlist>
-    </para>
-   </listitem>
-  </orderedlist>
- </para>
+ <simpara>
+  Both Perl and PCRE2 change continually, so the exact set of differences
+  depends on the version of the PCRE2 library in use. Refer to the
+  <link xlink:href="&url.pcre2.perlcompat;">PCRE2 documentation on the
+  differences between PCRE2 and Perl</link> for an up-to-date list.
+ </simpara>
 </article>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/pcre/pattern.syntax.xml b/reference/pcre/pattern.syntax.xml
index 2089643135d0..d71c8b2c7bb6 100644
--- a/reference/pcre/pattern.syntax.xml
+++ b/reference/pcre/pattern.syntax.xml
@@ -31,7 +31,7 @@
   <simpara>
    When using the PCRE functions, it is required that the pattern is enclosed
    by <emphasis>delimiters</emphasis>. A delimiter can be any non-alphanumeric,
-   non-backslash, non-whitespace single-byte character.
+   non-backslash, non-NUL, non-whitespace single-byte character.
    Leading whitespace before a valid delimiter is silently ignored.
   </simpara>
   <note>