Document that $additional_headers may now be an array

Cf. <https://github.com/php/php-src/blob/PHP-7.2.4/UPGRADING#L219-L225>

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@344497 c90b9560-bf6c-de11-be94-00142212c4b1

appendices/migration72/other-changes.xml

@@ -14,6 +14,16 @@
   </para>
  </sect2>
 
+ <sect2 xml:id="migration72.other-changes.mail">
+  <title>Changes to <function>mail</function> and <function>mb_sendmail</function></title>
+
+  <para>
+   The $additional_headers parameter of <function>mail</function> and
+   <function>mb_sendmail</function> now also accepts an <type>array</type>
+   instead of a <type>string</type>.
+  </para>
+ </sect2>
+
  <sect2 xml:id="migration72.other-changes.lmdb-support">
   <title>LMDB support</title>
 

reference/mail/functions/mail.xml

@@ -13,7 +13,7 @@
    <methodparam><type>string</type><parameter>to</parameter></methodparam>
    <methodparam><type>string</type><parameter>subject</parameter></methodparam>
    <methodparam><type>string</type><parameter>message</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>additional_headers</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>additional_headers</parameter></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>additional_parameters</parameter></methodparam>
   </methodsynopsis>
   <para>
@@ -86,7 +86,7 @@ $text = str_replace("\n.", "\n..", $text);
      <term><parameter>additional_headers</parameter> (optional)</term>
      <listitem>
       <para>
-       String to be inserted at the end of the email header.
+       <type>String</type> or <type>array</type> to be inserted at the end of the email header.
       </para>
       <para>
        This is typically used to add extra headers (From, Cc, and Bcc).
@@ -94,6 +94,10 @@ $text = str_replace("\n.", "\n..", $text);
        If outside data are used to compose this header, the data should be sanitized
        so that no unwanted headers could be injected. 
       </para>
+      <para>
+       If an <type>array</type> is passed, its keys are the header names and its
+       values are the respective header values.
+      </para>
       <note>
        <para>
         <parameter>additional_headers</parameter> does not have mail header
@@ -189,6 +193,13 @@ $text = str_replace("\n.", "\n..", $text);
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>7.2.0</entry>
+       <entry>
+        The <parameter>additional_headers</parameter> parameter now also accepts
+        an <type>array</type>.
+       </entry>
+      </row>
       <row>
        <entry>4.2.3</entry>
        <entry>
@@ -243,6 +254,29 @@ $headers = 'From: webmaster@example.com' . "\r\n" .
     'Reply-To: webmaster@example.com' . "\r\n" .
     'X-Mailer: PHP/' . phpversion();
 
+mail($to, $subject, $message, $headers);
+?>
+]]>
+    </programlisting>
+   </example>
+   <example>
+    <title>Sending mail with extra headers as <type>array</type></title>
+    <para>
+     This example sends the same mail as the example immediately above, but
+     passes the additional headers as array (available as of PHP 7.2.0).
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$to      = 'nobody@example.com';
+$subject = 'the subject';
+$message = 'hello';
+$headers = array(
+    'From' => 'webmaster@example.com',
+    'Reply-To' => 'webmaster@example.com'
+    'X-Mailer' => 'PHP/' . phpversion()
+);
+
 mail($to, $subject, $message, $headers);
 ?>
 ]]>

reference/mbstring/functions/mb-send-mail.xml

@@ -13,7 +13,7 @@
    <methodparam><type>string</type><parameter>to</parameter></methodparam>
    <methodparam><type>string</type><parameter>subject</parameter></methodparam>
    <methodparam><type>string</type><parameter>message</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>additional_headers</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>additional_headers</parameter><initializer>&null;</initializer></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>additional_parameter</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
@@ -58,13 +58,17 @@
      <term><parameter>additional_headers</parameter> (optional)</term>
      <listitem>
       <para>
-       String to be inserted at the end of the email header.
+       <type>String</type> or <type>array</type> to be inserted at the end of the email header.
       </para>
       <para>
        This is typically used to add extra headers (From, Cc, and Bcc).
        Multiple extra headers should be separated with a CRLF (\r\n).
        Validate parameter not to be injected unwanted headers by attackers.
       </para>
+      <para>
+       If an <type>array</type> is passed, its keys are the header names and its
+       values are the respective header values.
+      </para>
       <note>
        <para>
         When sending mail, the mail <emphasis>must</emphasis> contain
@@ -130,6 +134,31 @@
   </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.2.0</entry>
+       <entry>
+        The <parameter>additional_headers</parameter> parameter now also accepts
+        an <type>array</type>.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>