reference/mail/functions/mail.xml
d43f29f6a628996d1b7c3be487dcff39450146bf
d43f29f6a628996d1b7c3be487dcff39450146bf
...
...
@@ -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,11 +86,17 @@ $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).
93
93
Multiple extra headers should be separated with a CRLF (\r\n).
94
+
If outside data are used to compose this header, the data should be sanitized
95
+
so that no unwanted headers could be injected.
96
+
</para>
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.
94
100
</para>
95
101
<note>
96
102
<para>
...
...
@@ -104,7 +110,7 @@ $text = str_replace("\n.", "\n..", $text);
104
110
message similar to <literal>Warning: mail(): "sendmail_from" not
105
111
set in php.ini or custom "From:" header missing</literal>.
106
112
The <literal>From</literal> header sets also
107
-
<literal>Return-Path</literal> under Windows.
113
+
<literal>Return-Path</literal> when sending directly via SMTP (Windows only).
108
114
</para>
109
115
</note>
110
116
<note>
...
...
@@ -120,10 +126,10 @@ $text = str_replace("\n.", "\n..", $text);
120
126
</listitem>
121
127
</varlistentry>
122
128
<varlistentry>
123
-
<term><parameter>additional_parameters</parameter> (optional)</term>
129
+
<term><parameter>additional_params</parameter> (optional)</term>
124
130
<listitem>
125
131
<para>
126
-
The <parameter>additional_parameters</parameter> parameter
132
+
The <parameter>additional_params</parameter> parameter
127
133
can be used to pass additional flags as command line options to the
128
134
program configured to be used when sending mail, as defined by the
129
135
<literal>sendmail_path</literal> configuration setting. For example,
...
...
@@ -131,6 +137,20 @@ $text = str_replace("\n.", "\n..", $text);
131
137
sendmail with the <literal>-f</literal> sendmail option.
132
138
</para>
133
139
<para>
140
+
This parameter is escaped by <function>escapeshellcmd</function> internally
141
+
to prevent command execution. <function>escapeshellcmd</function> prevents
142
+
command execution, but allows to add additional parameters. For security reasons,
143
+
it is recommended for the user to sanitize this parameter to avoid adding unwanted
144
+
parameters to the shell command.
145
+
</para>
146
+
<para>
147
+
Since <function>escapeshellcmd</function> is applied automatically, some characters
148
+
that are allowed as email addresses by internet RFCs cannot be used.
149
+
<function>mail</function> can not allow such characters, so in programs where the use of
150
+
such characters is required, alternative means of sending emails (such as using a framework
151
+
or a library) is recommended.
152
+
</para>
153
+
<para>
134
154
The user that the webserver runs as should be added as a trusted user to the
135
155
sendmail configuration to prevent a 'X-Warning' header from being added
136
156
to the message when the envelope sender (-f) is set using this method.
...
...
@@ -166,28 +186,10 @@ $text = str_replace("\n.", "\n..", $text);
166
186
</thead>
167
187
<tbody>
168
188
<row>
169
-
<entry>4.3.0 (Windows only)</entry>
170
-
<entry>
171
-
All custom headers (like From, Cc, Bcc and Date) are supported, and are
172
-
not case-sensitive.
173
-
(As custom headers are not interpreted by the MTA in the first place,
174
-
but are parsed by PHP, PHP < 4.3 only supported the Cc header element
175
-
and was case-sensitive).
176
-
</entry>
177
-
</row>
178
-
<row>
179
-
<entry>4.2.3</entry>
180
-
<entry>
181
-
The <parameter>additional_parameters</parameter> parameter is disabled in
182
-
<link linkend="ini.safe-mode">safe_mode</link> and the
183
-
<function>mail</function> function will expose a warning message
184
-
and return &false; when used.
185
-
</entry>
186
-
</row>
187
-
<row>
188
-
<entry>4.0.5</entry>
189
+
<entry>7.2.0</entry>
189
190
<entry>
190
-
The <parameter>additional_parameters</parameter> parameter was added.
191
+
The <parameter>additional_headers</parameter> parameter now also accepts
192
+
an <type>array</type>.
191
193
</entry>
192
194
</row>
193
195
</tbody>
...
...
@@ -241,9 +243,32 @@ mail($to, $subject, $message, $headers);
241
243
</programlisting>
242
244
</example>
243
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>
244
269
<title>Sending mail with an additional command line parameter.</title>
245
270
<para>
246
-
The <parameter>additional_parameters</parameter> parameter
271
+
The <parameter>additional_params</parameter> parameter
247
272
can be used to pass an additional parameter to the program configured
248
273
to use when sending mail using the <literal>sendmail_path</literal>.
249
274
</para>
...
...
@@ -264,14 +289,13 @@ mail('nobody@example.com', 'the subject', 'the message', null,
264
289
<programlisting role="php">
265
290
<![CDATA[
266
291
<?php
267
-
// multiple recipients
268
-
$to = 'aidan@example.com' . ', '; // note the comma
269
-
$to .= 'wez@example.com';
292
+
// Multiple recipients
293
+
$to = 'johny@example.com, sally@example.com'; // note the comma
270
294
271
-
// subject
295
+
// Subject
272
296
$subject = 'Birthday Reminders for August';
273
297
274
-
// message
298
+
// Message
275
299
$message = '
276
300
<html>
277
301
<head>
...
...
@@ -284,7 +308,7 @@ $message = '
284
308
<th>Person</th><th>Day</th><th>Month</th><th>Year</th>
285
309
</tr>
286
310
<tr>
287
-
<td>Joe</td><td>3rd</td><td>August</td><td>1970</td>
311
+
<td>Johny</td><td>10th</td><td>August</td><td>1970</td>
288
312
</tr>
289
313
<tr>
290
314
<td>Sally</td><td>17th</td><td>August</td><td>1973</td>
...
...
@@ -295,17 +319,17 @@ $message = '
295
319
';
296
320
297
321
// To send HTML mail, the Content-type header must be set
298
-
$headers = 'MIME-Version: 1.0' . "\r\n";
299
-
$headers .= 'Content-type: text/html; charset=iso-8859-1' . "\r\n";
322
+
$headers[] = 'MIME-Version: 1.0';
323
+
$headers[] = 'Content-type: text/html; charset=iso-8859-1';
300
324
301
325
// Additional headers
302
-
$headers .= 'To: Mary <mary@example.com>, Kelly <kelly@example.com>' . "\r\n";
303
-
$headers .= 'From: Birthday Reminder <birthday@example.com>' . "\r\n";
304
-
$headers .= 'Cc: birthdayarchive@example.com' . "\r\n";
305
-
$headers .= 'Bcc: birthdaycheck@example.com' . "\r\n";
326
+
$headers[] = 'To: Mary <mary@example.com>, Kelly <kelly@example.com>';
327
+
$headers[] = 'From: Birthday Reminder <birthday@example.com>';
328
+
$headers[] = 'Cc: birthdayarchive@example.com';
329
+
$headers[] = 'Bcc: birthdaycheck@example.com';
306
330
307
331
// Mail it
308
-
mail($to, $subject, $message, $headers);
332
+
mail($to, $subject, $message, implode("\r\n", $headers));
309
333
?>
310
334
]]>
311
335
</programlisting>
...
...
@@ -325,8 +349,8 @@ mail($to, $subject, $message, $headers);
325
349
&reftitle.notes;
326
350
<note>
327
351
<para>
328
-
The Windows implementation of <function>mail</function> differs in many
329
-
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
330
354
for composing messages but only operates on direct sockets which means a
331
355
<literal>MTA</literal> is needed listening on a network socket (which
332
356
can either on the localhost or a remote machine).
...
...
@@ -379,6 +403,7 @@ mail($to, $subject, $message, $headers);
379
403
&reftitle.seealso;
380
404
<para>
381
405
<simplelist>
406
+
<member><function>mb_send_mail</function></member>
382
407
<member><function>imap_mail</function></member>
383
408
<member><link xlink:href="&url.pear.package;Mail">PEAR::Mail</link></member>
384
409
<member><link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link></member>
...
...
@@ -386,8 +411,6 @@ mail($to, $subject, $message, $headers);
386
411
</para>
387
412
</refsect1>
388
413
</refentry>
389
-
390
-
391
414
<!-- Keep this comment at the end of the file
392
415
Local variables:
393
416
mode: sgml
394
417