From cd8ca758fe6e111d39c6464e99ba19dfb8dcd91e Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Tue, 12 May 2020 15:58:42 +0200
Subject: [PATCH] PHP 7.4: PCRE: document new $flags param for
 preg_replace_callback[_array]()

The PHP 7.4 `$flags` parameter as added to the `preg_replace_callback()` and `preg_replace_callback_array()` function was not yet included in the documentation.

In this PR, I'm
* Adding the parameter to the function signature.
* Adding minimal parameter documentation with a reference to the more detailed explanation in the parameter documentation of the [`preg_match()`](https://www.php.net/manual/en/function.preg-match.php) function.
* Adding a changelog entry for the parameter to each function.

Refs:
* https://github.com/php/php-src/pull/3958
* https://github.com/php/php-src/blob/2f1398dad934086b605073c51af3118c8eff28b1/UPGRADING#L304-L308
---
 .../functions/preg-replace-callback-array.xml | 39 +++++++++++++++++++
 .../pcre/functions/preg-replace-callback.xml  | 27 +++++++++++--
 2 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/reference/pcre/functions/preg-replace-callback-array.xml b/reference/pcre/functions/preg-replace-callback-array.xml
index 9d287085bef3..12dd1668e694 100644
--- a/reference/pcre/functions/preg-replace-callback-array.xml
+++ b/reference/pcre/functions/preg-replace-callback-array.xml
@@ -14,6 +14,7 @@
    <methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
    <methodparam choice="opt"><type>int</type><parameter role="reference">count</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
   <para>
    The behavior of this function is similar to
@@ -61,6 +62,20 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>flags</parameter></term>
+     <listitem>
+      <para>
+       <parameter>flags</parameter> can be a combination of the
+       <constant>PREG_OFFSET_CAPTURE</constant> and
+       <constant>PREG_UNMATCHED_AS_NULL</constant> flags, which influence the
+       format of the matches array.
+       See the description in
+       <link linkend="function.preg-match">preg_match()</link>
+       for more details.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -78,6 +93,30 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>7.4.0</entry>
+       <entry>
+        The <parameter>flags</parameter> parameter was added.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
diff --git a/reference/pcre/functions/preg-replace-callback.xml b/reference/pcre/functions/preg-replace-callback.xml
index 32c884f042d5..1934949b676e 100644
--- a/reference/pcre/functions/preg-replace-callback.xml
+++ b/reference/pcre/functions/preg-replace-callback.xml
@@ -15,6 +15,7 @@
    <methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
    <methodparam choice="opt"><type>int</type><parameter role="reference">count</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
   <para>
    The behavior of this function is almost identical to
@@ -64,7 +65,7 @@
       </para>
       <para>
        <example>
-        <title><function>preg_replace_callback</function> and 
+        <title><function>preg_replace_callback</function> and
         anonymous function</title>
         <programlisting role="php">
 <![CDATA[
@@ -118,6 +119,20 @@ fclose($fp);
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>flags</parameter></term>
+     <listitem>
+      <para>
+       <parameter>flags</parameter> can be a combination of the
+       <constant>PREG_OFFSET_CAPTURE</constant> and
+       <constant>PREG_UNMATCHED_AS_NULL</constant> flags, which influence the
+       format of the matches array.
+       See the description in
+       <link linkend="function.preg-match">preg_match()</link>
+       for more details.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -131,7 +146,7 @@ fclose($fp);
   </para>
   <para>
    If matches are found, the new subject will be returned, otherwise
-   <parameter>subject</parameter> will be returned unchanged. 
+   <parameter>subject</parameter> will be returned unchanged.
   </para>
  </refsect1>
 
@@ -147,10 +162,16 @@ fclose($fp);
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>7.4.0</entry>
+       <entry>
+        The <parameter>flags</parameter> parameter was added.
+       </entry>
+      </row>
       <row>
        <entry>5.1.0</entry>
        <entry>
-        The <parameter>count</parameter> parameter was added
+        The <parameter>count</parameter> parameter was added.
        </entry>
       </row>
      </tbody>