[DOC-CVS] [doc-en] master: pcre: describe PREG_UNMATCHED_AS_NULL for trailing groups (#5272)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-21T10:52:41+02:00

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

pcre: describe PREG_UNMATCHED_AS_NULL for trailing groups (#5272)

Changed paths:
  M  reference/pcre/constants.xml
  M  reference/pcre/functions/preg-match.xml


Diff:

diff --git a/reference/pcre/constants.xml b/reference/pcre/constants.xml
index d3759e4a977b..f02c5b341d15 100644
--- a/reference/pcre/constants.xml
+++ b/reference/pcre/constants.xml
@@ -97,6 +97,10 @@
       <varname>$matches</varname> as &null; values. Without this flag, unmatched
       subpatterns are reported as empty strings, as if they were empty matches.
       Setting this flag allows to distinguish between these two cases.
+      With <function>preg_match</function>, trailing unmatched subpatterns are
+      omitted from <varname>$matches</varname> entirely unless this flag is
+      used; as of PHP 7.4.0 the flag reports them as &null;, so that
+      <varname>$matches</varname> always has the same size.
      </entry>
      <entry>7.2.0</entry>
     </row>
diff --git a/reference/pcre/functions/preg-match.xml b/reference/pcre/functions/preg-match.xml
index 8e8809f754e4..a1d428e3d278 100644
--- a/reference/pcre/functions/preg-match.xml
+++ b/reference/pcre/functions/preg-match.xml
@@ -119,8 +119,12 @@ Array
          <term><constant>PREG_UNMATCHED_AS_NULL</constant></term>
          <listitem>
           <para>
-           If this flag is passed, unmatched subpatterns are reported as &null;;
-           otherwise they are reported as an empty <type>string</type>.
+           If this flag is passed, unmatched subpatterns are reported as &null;
+           and are always included in the results (including trailing ones).
+           Without this flag, unmatched subpatterns that are followed by a
+           matched subpattern are reported as an empty <type>string</type>,
+           while trailing unmatched subpatterns are omitted from the results
+           entirely.
            <informalexample>
             <programlisting role="php">
 <![CDATA[
@@ -129,6 +133,12 @@ preg_match('/(a)(b)*(c)/', 'ac', $matches);
 var_dump($matches);
 preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
 var_dump($matches);
+
+// Trailing unmatched subpatterns:
+preg_match('/(a)(b)?(c)?/', 'a', $matches);
+var_dump($matches);
+preg_match('/(a)(b)?(c)?/', 'a', $matches, PREG_UNMATCHED_AS_NULL);
+var_dump($matches);
 ?>
 ]]>
             </programlisting>
@@ -155,6 +165,22 @@ array(4) {
   [3]=>
   string(1) "c"
 }
+array(2) {
+  [0]=>
+  string(1) "a"
+  [1]=>
+  string(1) "a"
+}
+array(4) {
+  [0]=>
+  string(1) "a"
+  [1]=>
+  string(1) "a"
+  [2]=>
+  NULL
+  [3]=>
+  NULL
+}
 ]]>
             </screen>
            </informalexample>
@@ -270,6 +296,17 @@ Array
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>7.4.0</entry>
+       <entry>
+        When the <constant>PREG_UNMATCHED_AS_NULL</constant> flag is used,
+        trailing unmatched capturing groups are now also included in the
+        result with the value &null; (or <literal>[null, -1]</literal> when
+        <constant>PREG_OFFSET_CAPTURE</constant> is also used), so that
+        <varname>$matches</varname> always has the same size. Previously,
+        they were omitted.
+       </entry>
+      </row>
       <row>
        <entry>7.2.0</entry>
        <entry>