...

...

@@ -13,8 +13,8 @@

13

13

<methodparam><type>string</type><parameter>to</parameter></methodparam>

14

14

<methodparam><type>string</type><parameter>subject</parameter></methodparam>

15

15

<methodparam><type>string</type><parameter>message</parameter></methodparam>

16

-

<methodparam choice="opt"><type>string</type><parameter>additional_headers</parameter></methodparam>

17

-

<methodparam choice="opt"><type>string</type><parameter>additional_parameters</parameter></methodparam>

16

+

<methodparam choice="opt"><type class="union"><type>array</type><type>string</type></type><parameter>additional_headers</parameter><initializer>[]</initializer></methodparam>

17

+

<methodparam choice="opt"><type>string</type><parameter>additional_params</parameter><initializer>""</initializer></methodparam>

18

18

</methodsynopsis>

19

19

<para>

20

20

Sends an email.

...

...

@@ -86,7 +86,7 @@ $text = str_replace("\n.", "\n..", $text);

86

86

<term><parameter>additional_headers</parameter> (optional)</term>

87

87

<listitem>

88

88

<para>

89

-

String to be inserted at the end of the email header.

89

+

<type>String</type> or <type>array</type> to be inserted at the end of the email header.

90

90

</para>

91

91

<para>

92

92

This is typically used to add extra headers (From, Cc, and Bcc).

...

...

@@ -94,14 +94,10 @@ $text = str_replace("\n.", "\n..", $text);

94

94

If outside data are used to compose this header, the data should be sanitized

95

95

so that no unwanted headers could be injected.

96

96

</para>

97

-

<note>

98

-

<para>

99

-

<parameter>additional_headers</parameter> does not have mail header

100

-

injection protection. Therefore, users must make sure specified headers

101

-

are safe and contains headers only. i.e. Never start mail body by putting

102

-

multiple newlines.

103

-

</para>

104

-

</note>

97

+

<para>

98

+

If an <type>array</type> is passed, its keys are the header names and its

99

+

values are the respective header values.

100

+

</para>

105

101

<note>

106

102

<para>

107

103

When sending mail, the mail <emphasis>must</emphasis> contain

...

...

@@ -114,7 +110,7 @@ $text = str_replace("\n.", "\n..", $text);

114

110

message similar to <literal>Warning: mail(): "sendmail_from" not

115

111

set in php.ini or custom "From:" header missing</literal>.

116

112

The <literal>From</literal> header sets also

117

-

<literal>Return-Path</literal> under Windows.

113

+

<literal>Return-Path</literal> when sending directly via SMTP (Windows only).

118

114

</para>

119

115

</note>

120

116

<note>

...

...

@@ -130,10 +126,10 @@ $text = str_replace("\n.", "\n..", $text);

130

126

</listitem>

131

127

</varlistentry>

132

128

<varlistentry>

133

-

<term><parameter>additional_parameters</parameter> (optional)</term>

129

+

<term><parameter>additional_params</parameter> (optional)</term>

134

130

<listitem>

135

131

<para>

136

-

The <parameter>additional_parameters</parameter> parameter

132

+

The <parameter>additional_params</parameter> parameter

137

133

can be used to pass additional flags as command line options to the

138

134

program configured to be used when sending mail, as defined by the

139

135

<literal>sendmail_path</literal> configuration setting. For example,

...

...

@@ -190,12 +186,10 @@ $text = str_replace("\n.", "\n..", $text);

190

186

</thead>

191

187

<tbody>

192

188

<row>

193

-

<entry>4.2.3</entry>

189

+

<entry>7.2.0</entry>

194

190

<entry>

195

-

The <parameter>additional_parameters</parameter> parameter is disabled in

196

-

<link linkend="ini.safe-mode">safe_mode</link> and the

197

-

<function>mail</function> function will expose a warning message

198

-

and return &false; when used.

191

+

The <parameter>additional_headers</parameter> parameter now also accepts

192

+

an <type>array</type>.

199

193

</entry>

200

194

</row>

201

195

</tbody>

...

...

@@ -249,9 +243,32 @@ mail($to, $subject, $message, $headers);

249

243

</programlisting>

250

244

</example>

251

245

<example>

246

+

<title>Sending mail with extra headers as <type>array</type></title>

247

+

<para>

248

+

This example sends the same mail as the example immediately above, but

249

+

passes the additional headers as array (available as of PHP 7.2.0).

250

+

</para>

251

+

<programlisting role="php">

252

+

<![CDATA[

253

+

<?php

254

+

$to = 'nobody@example.com';

255

+

$subject = 'the subject';

256

+

$message = 'hello';

257

+

$headers = array(

258

+

'From' => 'webmaster@example.com',

259

+

'Reply-To' => 'webmaster@example.com',

260

+

'X-Mailer' => 'PHP/' . phpversion()

261

+

);

262

+

263

+

mail($to, $subject, $message, $headers);

264

+

?>

265

+

]]>

266

+

</programlisting>

267

+

</example>

268

+

<example>

252

269

<title>Sending mail with an additional command line parameter.</title>

253

270

<para>

254

-

The <parameter>additional_parameters</parameter> parameter

271

+

The <parameter>additional_params</parameter> parameter

255

272

can be used to pass an additional parameter to the program configured

256

273

to use when sending mail using the <literal>sendmail_path</literal>.

257

274

</para>

...

...

@@ -332,8 +349,8 @@ mail($to, $subject, $message, implode("\r\n", $headers));

332

349

&reftitle.notes;

333

350

<note>

334

351

<para>

335

-

The Windows implementation of <function>mail</function> differs in many

336

-

ways from the Unix implementation. First, it doesn't use a local binary

352

+

The SMTP implementation (Windows only) of <function>mail</function> differs in many

353

+

ways from the sendmail implementation. First, it doesn't use a local binary

337

354

for composing messages but only operates on direct sockets which means a

338

355

<literal>MTA</literal> is needed listening on a network socket (which

339

356

can either on the localhost or a remote machine).

...

...

@@ -386,6 +403,7 @@ mail($to, $subject, $message, implode("\r\n", $headers));

386

403

&reftitle.seealso;

387

404

<para>

388

405

<simplelist>

406

+

<member><function>mb_send_mail</function></member>

389

407

<member><function>imap_mail</function></member>

390

408

<member><link xlink:href="&url.pear.package;Mail">PEAR::Mail</link></member>

391

409

<member><link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link></member>

...

...

@@ -393,8 +411,6 @@ mail($to, $subject, $message, implode("\r\n", $headers));

393

411

</para>

394

412

</refsect1>

395

413

</refentry>

396

-

397

-

398

414

<!-- Keep this comment at the end of the file

399

415

Local variables:

400

416

mode: sgml

401

417