mail.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: d43f29f6a628996d1b7c3be487dcff39450146bf Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<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 class="union"><type>array</type><type>string</type></type><parameter>additional_headers</parameter><initializer>[]</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>additional_params</parameter><initializer>""</initializer></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 &lt;user@example.com&gt;</member>
        <member>User &lt;user@example.com&gt;, Another User &lt;anotheruser@example.com&gt;</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, и Bcc).
       Дополнительные заголовки разделяют комбинацией символов CRLF (\r\n).
       Если в составлении заголовка участвуют внешние данные,
       их очищают, чтобы исключить риск внедрения нежелательных заголовков.
      </para>
      <para>
       Если передан массив, то его ключи будут именами заголовка, а значения значениями.
      </para>
      <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> при прямой отправке через SMTP-сервер (только 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_params</parameter> (необязательный)</term>
     <listitem>
      <para>
       Параметр <parameter>additional_params</parameter> задают,
       чтобы передать дополнительные флаги в виде аргументов
       командной строки для программы, настроенной в директиве <literal>sendmail_path</literal>
       для отправки писем. Например, этим пользуются при отправке письма
       агентом sendmail с аргументом <literal>-f</literal>,
       чтобы установить адрес отправителя конверта.
      </para>
      <para>
       Параметр автоматически экранируется функцией <function>escapeshellcmd</function>,
       чтобы предотвратить выполнение команды. Функция <function>escapeshellcmd</function>
       исключает выполнение команды,
       но разрешает дополнительные параметры. По соображениям безопасности
       рекомендовано очищать этот параметр, чтобы не допустить добавления нежелательных параметров
       в команду командной оболочки.
      </para>
      <para>
       Поскольку функция <function>escapeshellcmd</function> обрабатывает параметр автоматически,
       часть символов, разрешённых интернет-стандартами
       в качестве адресов электронной почты, нельзя указывать.
       Функция <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>
     </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_params</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';
$headers[] = 'Content-type: text/html; charset=iso-8859-1';

// Дополнительные заголовки
$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>
    Реализация SMTP (только Windows) функции <function>mail</function> в Windows во многом отличается от
    реализации в агенте sendmail. Во-первых, она не использует локальную программу для
    составления писем, а работает непосредственно с сокетами, что означает что
    необходим почтовый агент (<literal>MTA</literal>), ожидающий
    соединений на сокете (который может быть как на локальной, или localhost,
    так и на удалённой машине).
   </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> не должен быть адресом вида
    &quot;Something &lt;someone@example.com&gt;&quot;. Команда
    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
-->