reference/mail/functions/mail.xml
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.
...
...
@@ -63,8 +63,8 @@
63
63
Message to be sent.
64
64
</para>
65
65
<para>
66
-
Each line should be separated with a LF (\n). Lines should not be larger
67
-
than 70 characters.
66
+
Each line should be separated with a CRLF (\r\n). Lines should not be
67
+
larger than 70 characters.
68
68
</para>
69
69
<caution>
70
70
<para>
...
...
@@ -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,13 +110,14 @@ $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>
111
117
<para>
112
118
If messages are not received, try using a LF (\n) only.
113
-
Some poor quality Unix mail transfer agents replace LF by CRLF
119
+
Some Unix mail transfer agents (most notably
120
+
<link xlink:href="&url.qmail;">qmail</link>) replace LF by CRLF
114
121
automatically (which leads to doubling CR if CRLF is used).
115
122
This should be a last resort, as it does not comply with
116
123
<link xlink:href="&url.rfc;2822">RFC 2822</link>.
...
...
@@ -119,10 +126,10 @@ $text = str_replace("\n.", "\n..", $text);
119
126
</listitem>
120
127
</varlistentry>
121
128
<varlistentry>
122
-
<term><parameter>additional_parameters</parameter> (optional)</term>
129
+
<term><parameter>additional_params</parameter> (optional)</term>
123
130
<listitem>
124
131
<para>
125
-
The <parameter>additional_parameters</parameter> parameter
132
+
The <parameter>additional_params</parameter> parameter
126
133
can be used to pass additional flags as command line options to the
127
134
program configured to be used when sending mail, as defined by the
128
135
<literal>sendmail_path</literal> configuration setting. For example,
...
...
@@ -130,6 +137,20 @@ $text = str_replace("\n.", "\n..", $text);
130
137
sendmail with the <literal>-f</literal> sendmail option.
131
138
</para>
132
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>
133
154
The user that the webserver runs as should be added as a trusted user to the
134
155
sendmail configuration to prevent a 'X-Warning' header from being added
135
156
to the message when the envelope sender (-f) is set using this method.
...
...
@@ -165,28 +186,10 @@ $text = str_replace("\n.", "\n..", $text);
165
186
</thead>
166
187
<tbody>
167
188
<row>
168
-
<entry>4.3.0 (Windows only)</entry>
169
-
<entry>
170
-
All custom headers (like From, Cc, Bcc and Date) are supported, and are
171
-
not case-sensitive.
172
-
(As custom headers are not interpreted by the MTA in the first place,
173
-
but are parsed by PHP, PHP &lt; 4.3 only supported the Cc header element
174
-
and was case-sensitive).
175
-
</entry>
176
-
</row>
177
-
<row>
178
-
<entry>4.2.3</entry>
179
-
<entry>
180
-
The <parameter>additional_parameters</parameter> parameter is disabled in
181
-
<link linkend="ini.safe-mode">safe_mode</link> and the
182
-
<function>mail</function> function will expose a warning message
183
-
and return &false; when used.
184
-
</entry>
185
-
</row>
186
-
<row>
187
-
<entry>4.0.5</entry>
189
+
<entry>7.2.0</entry>
188
190
<entry>
189
-
The <parameter>additional_parameters</parameter> parameter was added.
191
+
The <parameter>additional_headers</parameter> parameter now also accepts
192
+
an <type>array</type>.
190
193
</entry>
191
194
</row>
192
195
</tbody>
...
...
@@ -207,10 +210,10 @@ $text = str_replace("\n.", "\n..", $text);
207
210
<![CDATA[
208
211
<?php
209
212
// The message
210
-
$message = "Line 1\nLine 2\nLine 3";
213
+
$message = "Line 1\r\nLine 2\r\nLine 3";
211
214

212
215
// In case any of our lines are larger than 70 characters, we should use wordwrap()
213
-
$message = wordwrap($message, 70);
216
+
$message = wordwrap($message, 70, "\r\n");
214
217

215
218
// Send
216
219
mail('caffeinated@example.com', 'My Subject', $message);
...
...
@@ -240,9 +243,32 @@ mail($to, $subject, $message, $headers);
240
243
</programlisting>
241
244
</example>
242
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>
243
269
<title>Sending mail with an additional command line parameter.</title>
244
270
<para>
245
-
The <parameter>additional_parameters</parameter> parameter
271
+
The <parameter>additional_params</parameter> parameter
246
272
can be used to pass an additional parameter to the program configured
247
273
to use when sending mail using the <literal>sendmail_path</literal>.
248
274
</para>
...
...
@@ -263,14 +289,13 @@ mail('nobody@example.com', 'the subject', 'the message', null,
263
289
<programlisting role="php">
264
290
<![CDATA[
265
291
<?php
266
-
// multiple recipients
267
-
$to = 'aidan@example.com' . ', '; // note the comma
268
-
$to .= 'wez@example.com';
292
+
// Multiple recipients
293
+
$to = 'johny@example.com, sally@example.com'; // note the comma
269
294

270
-
// subject
295
+
// Subject
271
296
$subject = 'Birthday Reminders for August';
272
297

273
-
// message
298
+
// Message
274
299
$message = '
275
300
<html>
276
301
<head>
...
...
@@ -283,7 +308,7 @@ $message = '
283
308
<th>Person</th><th>Day</th><th>Month</th><th>Year</th>
284
309
</tr>
285
310
<tr>
286
-
<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>
287
312
</tr>
288
313
<tr>
289
314
<td>Sally</td><td>17th</td><td>August</td><td>1973</td>
...
...
@@ -294,17 +319,17 @@ $message = '
294
319
';
295
320

296
321
// To send HTML mail, the Content-type header must be set
297
-
$headers = 'MIME-Version: 1.0' . "\r\n";
298
-
$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';
299
324

300
325
// Additional headers
301
-
$headers .= 'To: Mary <mary@example.com>, Kelly <kelly@example.com>' . "\r\n";
302
-
$headers .= 'From: Birthday Reminder <birthday@example.com>' . "\r\n";
303
-
$headers .= 'Cc: birthdayarchive@example.com' . "\r\n";
304
-
$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';
305
330

306
331
// Mail it
307
-
mail($to, $subject, $message, $headers);
332
+
mail($to, $subject, $message, implode("\r\n", $headers));
308
333
?>
309
334
]]>
310
335
</programlisting>
...
...
@@ -324,8 +349,8 @@ mail($to, $subject, $message, $headers);
324
349
&reftitle.notes;
325
350
<note>
326
351
<para>
327
-
The Windows implementation of <function>mail</function> differs in many
328
-
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
329
354
for composing messages but only operates on direct sockets which means a
330
355
<literal>MTA</literal> is needed listening on a network socket (which
331
356
can either on the localhost or a remote machine).
...
...
@@ -378,6 +403,7 @@ mail($to, $subject, $message, $headers);
378
403
&reftitle.seealso;
379
404
<para>
380
405
<simplelist>
406
+
<member><function>mb_send_mail</function></member>
381
407
<member><function>imap_mail</function></member>
382
408
<member><link xlink:href="&url.pear.package;Mail">PEAR::Mail</link></member>
383
409
<member><link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link></member>
...
...
@@ -385,8 +411,6 @@ mail($to, $subject, $message, $headers);
385
411
</para>
386
412
</refsect1>
387
413
</refentry>
388
-

389
-

390
414
<!-- Keep this comment at the end of the file
391
415
Local variables:
392
416
mode: sgml
393
417