mirror of
https://github.com/php/doc-ru.git
synced 2025-07-30 12:57:40 +00:00
d38e1f2cdd
git-svn-id: https://svn.php.net/repository/phpdoc/ru/trunk@347786 c90b9560-bf6c-de11-be94-00142212c4b1
453 lines
18 KiB
XML
453 lines
18 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
||
<!-- EN-Revision: ce9318501243db8c1bdfd2aa64595c772f92427e Maintainer: shein Status: ready -->
|
||
<!-- Reviewed: yes -->
|
||
<!-- $Revision$ -->
|
||
<refentry xml:id="function.mail" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||
<refnamediv>
|
||
<refname>mail</refname>
|
||
<refpurpose>Отправляет электронную почту</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsect1 role="description">
|
||
&reftitle.description;
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname>mail</methodname>
|
||
<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>mixed</type><parameter>additional_headers</parameter></methodparam>
|
||
<methodparam choice="opt"><type>string</type><parameter>additional_parameters</parameter></methodparam>
|
||
</methodsynopsis>
|
||
<para>
|
||
Отправляет электронную почту.
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="parameters">
|
||
&reftitle.parameters;
|
||
<para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><parameter>to</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Получатель, или получатели письма.
|
||
</para>
|
||
<para>
|
||
Формат этого параметра должен соответствовать
|
||
<link xlink:href="&url.rfc;2822">RFC 2822</link>. Несколько примеров:
|
||
<simplelist>
|
||
<member>user@example.com</member>
|
||
<member>user@example.com, anotheruser@example.com</member>
|
||
<member>User <user@example.com></member>
|
||
<member>User <user@example.com>, Another User <anotheruser@example.com></member>
|
||
</simplelist>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>subject</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Тема отправляемого письма.
|
||
</para>
|
||
<caution>
|
||
<para>
|
||
Тема должна соответствовать <link xlink:href="&url.rfc;2047">RFC 2047</link>.
|
||
</para>
|
||
</caution>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>message</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Отправляемое сообщение.
|
||
</para>
|
||
<para>
|
||
Каждая строка должна быть отделена символом CRLF (\r\n).
|
||
Строки не должны быть длиннее 70 символов.
|
||
</para>
|
||
<caution>
|
||
<para>
|
||
(Только для Windows) Если PHP передаёт данные напрямую SMTP-серверу и
|
||
в начале строки стоит точка, то она будет удалена. Чтобы избежать этого замените
|
||
все такие точки на две.
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
$text = str_replace("\n.", "\n..", $text);
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</para>
|
||
</caution>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>additional_headers</parameter> (необязательный)</term>
|
||
<listitem>
|
||
<para>
|
||
Строка или массив, которые будут вставлены в конец отправляемых заголовков письма.
|
||
</para>
|
||
<para>
|
||
Обычно используется для добавления дополнительных заголовков (From, Cc, and Bcc).
|
||
Несколько дополнительных заголовков должны быть разделены CRLF (\r\n).
|
||
Если для составления этого заголовка используются внешние данные,
|
||
то они должны быть проверены для избежания инъекций нежелательных заголовков.
|
||
</para>
|
||
<para>
|
||
Если передан массив, то его ключи будут именами заголовка, а значения значениями.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
До PHP 5.4.42 и 5.5.27, параметр <parameter>additional_headers</parameter>
|
||
не имел защиты от инъекции.
|
||
Так что пользователи должны удостовериться, что передаваемые заголовки
|
||
безопасны и содержат только заголовки. т.е. не содержат несколько
|
||
переводов строк подряд, что стартует тело сообщения.
|
||
</para>
|
||
</note>
|
||
<note>
|
||
<para>
|
||
При отправке письмо <emphasis>должно</emphasis> содержать
|
||
заголовок <literal>From</literal>. Он может быть установлен с помощью
|
||
параметра <parameter>additional_headers</parameter>, или значение
|
||
по умолчанию может быть установлено в &php.ini;.
|
||
</para>
|
||
<para>
|
||
Если заголовок отсутствует, будет сгенерировано сообщение об ошибке
|
||
вида <literal>Warning: mail(): "sendmail_from" not
|
||
set in php.ini or custom "From:" header missing</literal>.
|
||
Заголовок <literal>From</literal> также определяет заголовок
|
||
<literal>Return-Path</literal> в Windows.
|
||
</para>
|
||
</note>
|
||
<note>
|
||
<para>
|
||
Если сообщения не отправляются, попробуйте использовать только LF (\n).
|
||
Некоторые агенты пересылки сообщений Unix (особенно
|
||
<link xlink:href="&url.qmail;">qmail</link>) автоматически заменяют LF на CRLF
|
||
(что приводит к двойному CR, если использовалось CRLF).
|
||
Используйте эту меру в крайнем случае, так как это нарушает
|
||
<link xlink:href="&url.rfc;2822">RFC 2822</link>.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>additional_parameters</parameter> (необязательный)</term>
|
||
<listitem>
|
||
<para>
|
||
Параметр <parameter>additional_parameters</parameter> может быть
|
||
использован для передачи дополнительных флагов в виде аргументов
|
||
командной строки для программы сконфигурированной для отправки писем,
|
||
указанной директивой <literal>sendmail_path</literal>. Например, можно
|
||
установить отправителя письма при использовании sendmail с помощью опции
|
||
<literal>-f</literal>.
|
||
</para>
|
||
<para>
|
||
Параметр автоматически экранируется функцией <function>escapeshellcmd</function>,
|
||
чтобы не допустить выполнение команд. Но <function>escapeshellcmd</function>
|
||
позволяет добавлять дополнительные параметры. В целях безопасности
|
||
рекомендуется проверять и очищать этот параметр.
|
||
</para>
|
||
<para>
|
||
Так как <function>escapeshellcmd</function> применяется автоматически, то нельзя использовать
|
||
некоторые символы, допустимые к использованию в email-адресах некоторыми RFC.
|
||
<function>mail</function> не допускает такие символы, поэтому в программах, в которых они требуются,
|
||
рекомендуется использовать альтернативы для их отправки (например фреймворки или библиотеки).
|
||
</para>
|
||
<para>
|
||
Пользователь, под которым работает веб-сервер должен быть добавлен в список
|
||
доверенных в конфигурации sendmail для того чтобы избежать добавления заголовка
|
||
'X-Warning' при указании отправителя с помощью опции (-f).
|
||
Для пользователей sendmail - это файл <filename>/etc/mail/trusted-users</filename>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="returnvalues">
|
||
&reftitle.returnvalues;
|
||
<para>
|
||
Возвращает &true;, если письмо было принято для передачи, иначе &false;.
|
||
</para>
|
||
<para>
|
||
Важно заметить, что то что письмо было принято для передачи вовсе НЕ означает
|
||
что оно достигло получателя.
|
||
</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>
|
||
Параметр <parameter>additional_headers</parameter> может принимать
|
||
значения типа массив.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry>5.4.42, 5.5.27</entry>
|
||
<entry>
|
||
Добавлена защита от атак инъекцией в заголовок для параметра
|
||
<parameter>additional_headers</parameter>. Это значит, что множественные
|
||
последовательные переводы строк более не допустимы.
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="examples">
|
||
&reftitle.examples;
|
||
<para>
|
||
<example>
|
||
<title>Отправка письма.</title>
|
||
<para>
|
||
Использование функции <function>mail</function> для отправки простого письма:
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
// Сообщение
|
||
$message = "Line 1\r\nLine 2\r\nLine 3";
|
||
|
||
// На случай если какая-то строка письма длиннее 70 символов мы используем wordwrap()
|
||
$message = wordwrap($message, 70, "\r\n");
|
||
|
||
// Отправляем
|
||
mail('caffeinated@example.com', 'My Subject', $message);
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Отправка письма с дополнительными заголовками.</title>
|
||
<para>
|
||
Добавление простых заголовков, сообщающих почтовому агенту
|
||
адреса From и Reply-To:
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
$to = 'nobody@example.com';
|
||
$subject = 'the subject';
|
||
$message = 'hello';
|
||
$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>Отправка письма с дополнительными заголовками, переданными массивом</title>
|
||
<para>
|
||
В этом примере посылается то же письмо, что и в примере выше, но
|
||
дополнительные заголовки задаются массивом (доступно с 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);
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Отправка письма с дополнительными аргументами командной строки.</title>
|
||
<para>
|
||
Параметр <parameter>additional_parameters</parameter> может быть использован
|
||
для передачи дополнительных параметров программе, используемой для отправки
|
||
писем с помощью директивы <literal>sendmail_path</literal>.
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
mail('nobody@example.com', 'the subject', 'the message', null,
|
||
'-fwebmaster@example.com');
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Отправка HTML-сообщения</title>
|
||
<para>
|
||
С помощью функции <function>mail</function> также можно отправить и HTML-письмо.
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
// несколько получателей
|
||
$to = 'johny@example.com, sally@example.com'; // обратите внимание на запятую
|
||
|
||
// тема письма
|
||
$subject = 'Birthday Reminders for August';
|
||
|
||
// текст письма
|
||
$message = '
|
||
<html>
|
||
<head>
|
||
<title>Birthday Reminders for August</title>
|
||
</head>
|
||
<body>
|
||
<p>Here are the birthdays upcoming in August!</p>
|
||
<table>
|
||
<tr>
|
||
<th>Person</th><th>Day</th><th>Month</th><th>Year</th>
|
||
</tr>
|
||
<tr>
|
||
<td>Johny</td><td>10th</td><td>August</td><td>1970</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Sally</td><td>17th</td><td>August</td><td>1973</td>
|
||
</tr>
|
||
</table>
|
||
</body>
|
||
</html>
|
||
';
|
||
|
||
// Для отправки HTML-письма должен быть установлен заголовок Content-type
|
||
$headers = 'MIME-Version: 1.0' . "\r\n";
|
||
$headers .= 'Content-type: text/html; charset=iso-8859-1' . "\r\n";
|
||
|
||
// Дополнительные заголовки
|
||
$headers[] = 'To: Mary <mary@example.com>, Kelly <kelly@example.com>';
|
||
$headers[] = 'From: Birthday Reminder <birthday@example.com>';
|
||
$headers[] = 'Cc: birthdayarchive@example.com';
|
||
$headers[] = 'Bcc: birthdaycheck@example.com';
|
||
|
||
// Отправляем
|
||
mail($to, $subject, $message, implode("\r\n", $headers));
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
<para>
|
||
<note>
|
||
<para>
|
||
Для отправки HTML или других комплексных сообщений рекомендуется использовать
|
||
PEAR-пакет <link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link>.
|
||
</para>
|
||
</note>
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="notes">
|
||
&reftitle.notes;
|
||
<note>
|
||
<para>
|
||
Реализация функции <function>mail</function> в Windows во многом отличается от
|
||
реализации в Unix. Во-первых, она не использует локальную программу для
|
||
составления писем, а работает непосредственно с сокетами, что означает что
|
||
необходим почтовый агент (<literal>MTA</literal>), ожидающий
|
||
соединений на сокете (может быть как на локальном так и на
|
||
удаленном сервере).
|
||
</para>
|
||
<para>
|
||
Во-вторых, дополнительные заголовки вроде:
|
||
<literal>From:</literal>,
|
||
<literal>Cc:</literal>,
|
||
<literal>Bcc:</literal> и
|
||
<literal>Date:</literal>
|
||
интерпретируются в первую очередь <emphasis role="strong">не</emphasis>,
|
||
<literal>MTA</literal>, а PHP.
|
||
</para>
|
||
<para>
|
||
Поэтому параметр <parameter>to</parameter> не должен быть адресом вида
|
||
"Something <someone@example.com>". Команда
|
||
mail может неправильно интерпретировать этот адрес во время передачи
|
||
данных MTA.
|
||
</para>
|
||
</note>
|
||
|
||
<note>
|
||
<para>
|
||
Не следует использовать функцию <function>mail</function> для отправки
|
||
большого количества писем в цикле. Функция открывает и закрывает
|
||
соединение с SMTP-сервером для каждого письма, что не очень эффективно.
|
||
</para>
|
||
<para>
|
||
Для отправки большого количества сообщений обратите внимание на пакеты
|
||
<link xlink:href="&url.pear.package;Mail">PEAR::Mail</link> и
|
||
<link xlink:href="&url.pear.package;Mail_Queue">PEAR::Mail_Queue</link>.
|
||
</para>
|
||
</note>
|
||
|
||
<note>
|
||
<para>
|
||
Полезные RFC:
|
||
<link xlink:href="&url.rfc;1896">RFC 1896</link>,
|
||
<link xlink:href="&url.rfc;2045">RFC 2045</link>,
|
||
<link xlink:href="&url.rfc;2046">RFC 2046</link>,
|
||
<link xlink:href="&url.rfc;2047">RFC 2047</link>,
|
||
<link xlink:href="&url.rfc;2048">RFC 2048</link>,
|
||
<link xlink:href="&url.rfc;2049">RFC 2049</link> и
|
||
<link xlink:href="&url.rfc;2822">RFC 2822</link>.
|
||
</para>
|
||
</note>
|
||
</refsect1>
|
||
|
||
<refsect1 role="seealso">
|
||
&reftitle.seealso;
|
||
<para>
|
||
<simplelist>
|
||
<member><function>mb_send_mail</function></member>
|
||
<member><function>imap_mail</function></member>
|
||
<member><link xlink:href="&url.pear.package;Mail">PEAR::Mail</link></member>
|
||
<member><link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link></member>
|
||
</simplelist>
|
||
</para>
|
||
</refsect1>
|
||
</refentry>
|
||
|
||
|
||
<!-- Keep this comment at the end of the file
|
||
Local variables:
|
||
mode: sgml
|
||
sgml-omittag:t
|
||
sgml-shorttag:t
|
||
sgml-minimize-attributes:nil
|
||
sgml-always-quote-attributes:t
|
||
sgml-indent-step:1
|
||
sgml-indent-data:t
|
||
indent-tabs-mode:nil
|
||
sgml-parent-document:nil
|
||
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
||
sgml-exposed-tags:nil
|
||
sgml-local-catalogs:nil
|
||
sgml-local-ecat-files:nil
|
||
End:
|
||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||
vim: et tw=78 syn=sgml
|
||
vi: ts=1 sw=1
|
||
-->
|