PHP: полный мануал с примерами, функциями и ООП

Зачем сайту почта и где заканчивается работа PHP

Покупатель оформил заказ; сайт должен сообщить номер и следующий шаг. В этой задаче есть две разные части: правильно собрать письмо и передать его почтовой системе. Пользовательская функция не управляет напрямую папкой «Входящие». Даже успешная передача дальше может закончиться задержкой, отказом адресата или попаданием в спам.

<?php
declare(strict_types=1);

$to = 'customer@example.invalid';
$subject = 'Order 17 received';
$message = "Order: 17\r\nStatus: received\r\n";
echo $to, "\n", $subject, "\n";
echo str_replace("\r\n", "\n", $message);

customer@example.invalid
Order 17 received
Order: 17
Status: received

Встроенная функция и внешний транспорт

На Unix mail обычно передаёт письмо sendmail-совместимой программе. Это может быть sendmail либо wrapper Postfix/qmail и другой почтовой системы. В требованиях сборки PHP указан поиск sendmail в PATH и стандартных системных каталогах; пользователь сборки должен иметь доступ. На рабочем сервере одной функции PHP недостаточно: нужен установленный и настроенный маршрут обработки писем.

Windows имеет встроенный простой SMTP-транспорт, который соединяется с указанным MTA. В нём нет автоматически предоставленного аккаунта, STARTTLS или SMTP AUTH. Если нужен защищённый SMTP провайдера с авторизацией, используют библиотеку/транспорт с такой поддержкой. Настройка sendmail_path переключает на внешнюю программу и в Windows.

Проверьте конфигурацию нужного PHP SAPI и наличие функции через function_exists. Успешный запуск в терминале не доказывает, что веб-процесс использует тот же ini или имеет те же права. Адрес, порт, внешняя программа и аутентификация — разные настройки.

Все настройки Mail

INI_SYSTEM меняется в конфигурации запуска, INI_PERDIR — на разрешённом уровне каталога/сервера, INI_ALL допускает runtime-изменение. Имя SMTP пишется именно так; оно не добавляет TLS одним изменением порта. Не публикуйте phpinfo и почтовые журналы с внутренними путями для посетителей.

Конверт, заголовки и тело — три разных уровня

Сайт отправляет письмо от контролируемого проектом адреса. Адрес посетителя после проверки можно использовать как Reply-To, если это соответствует назначению формы. HTML-экранирование не предотвращает внедрение почтового заголовка: контекст другой. В шаблоне HTML-тела htmlspecialchars защищает вставляемый текст, но не становится валидатором email.

Русский текст, MIME и длина строки

Кодировка темы и кодировка тела независимы. Для темы используется encoded-word RFC2047; для тела указывают charset и Content-Transfer-Encoding. Base64 удобен для точной транспортной передачи UTF-8, но увеличивает размер. Для сложного HTML, вложений, multipart/alternative и международных адресов разумнее библиотека, которая формирует MIME целиком.

<?php
declare(strict_types=1);

$subject = 'Заказ 17 принят';
$encodedSubject = mb_encode_mimeheader($subject, 'UTF-8', 'B', "\r\n");
$plain = "Спасибо за заказ.\r\n";
$encodedBody = chunk_split(base64_encode($plain), 76, "\r\n");
var_dump(mb_decode_mimeheader($encodedSubject) === $subject);
var_dump(base64_decode($encodedBody, true) === $plain);

bool(true)
bool(true)

Официальный простой пример mail предлагает переносить строки примерно на70 символов. RFC5322 рекомендует до78 и ограничивает строку998 символами без CRLF; у конкретного MIME-кодирования свои правила (Base64 — до76). Это не повод применять wordwrap вслепую к UTF-8, URL, заголовку или готовому HTML: можно разорвать данные. Генератор MIME выбирает переносы по типу содержимого.

С PHP8 обычные заголовки формируются с CRLF. Старые qmail-совместимые цепочки иногда сами преобразуют LF и получают двойной CR; для подтверждённой несовместимости есть mail.mixed_lf_and_crlf. Не исправляйте все письма глобальной заменой переносов «на удачу». В Windows PHP8.5.11 сам удваивает точки после в SMTP DATA; старый совет повторить str_replace(" .", " ..", ...) способен удвоить их лишний раз. Этот край проверяйте на выбранном транспорте, особенно при произвольном сыром теле.

Как не превратить форму обратной связи в почтовый ретранслятор

Пусть HTML-поле называется reply_email. После обычного POST-отправления формы PHP получает его в $_POST["reply_email"]. Клиент может прислать вместо строки массив, огромный текст либо строку с переводами строк. Сначала метод, CSRF/разрешённость действия и тип поля, затем ограничения и формат; получатель и отправитель задаются конфигурацией сайта.

<?php
declare(strict_types=1);

function checkedReplyEmail(mixed $raw): string {
    if (!is_string($raw) || strlen($raw) > 254) throw new InvalidArgumentException('Нужен короткий адрес');
    if (str_contains($raw, "\r") || str_contains($raw, "\n") || str_contains($raw, "\0")) {
        throw new InvalidArgumentException('Управляющие символы запрещены');
    }
    $email = trim($raw);
    if (filter_var($email, FILTER_VALIDATE_EMAIL) === false) throw new InvalidArgumentException('Некорректный формат');
    return $email;
}
foreach (['buyer@example.invalid', ['unexpected'], "buyer@example.invalid\nBcc: other@example.invalid"] as $raw) {
    try { echo checkedReplyEmail($raw), "\n"; }
    catch (InvalidArgumentException $error) { echo "Отклонено\n"; }
}

buyer@example.invalid
Отклонено
Отклонено

Связанный полный HTML и обработка полей находятся в разделе форм, типы суперглобальных данных — в суперглобальных массивах. Ограничивайте размер тела, частоту и количество сообщений. Сохранение заявки должно иметь собственный результат; временная ошибка почты не должна молча уничтожать уже принятую заявку.

HTML-уведомление: содержимое из данных, не из произвольной разметки

<?php
declare(strict_types=1);

$productName = '<Ключ> & комплект';
$safeName = htmlspecialchars($productName, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
$html = '<p>Товар: ' . $safeName . '</p>';
echo $html, "\n";

<p>Товар: &lt;Ключ&gt; &amp; комплект</p>

Вложения, встроенные изображения, boundary и переносы заголовков требуют согласованного MIME. Исторический PHP Manual ссылается на PEAR::Mail, Mail_Mime и Mail_Queue; их роль сохраняем как указатель старых решений. Современный проект может выбрать PHPMailer либо Symfony Mailer через Composer. Они не заменяют разрешение отправителя и настройку доставляемости.

Почему true ещё не означает доставку

При PHP8.5 sendmail-сбой и неожиданное завершение внешнего процесса диагностируются полнее. Предупреждение не надо подавлять @ и выдавать посетителю «всё отправлено». В пользовательском ответе показывают понятный статус, в защищённом журнале — технические сведения без токенов и полного личного текста. Конкретный SMTP/MTA журнал — источник следующего шага.

После принятия сообщения возможна отдельная ошибка доставки. Если нужно отслеживание, храните ID задания, принятый статус транспорта и события доставки от выбранной системы отдельно. Открытие письма тоже не доказывается одним результатом mail.

Большая рассылка, очередь и повторные попытки

mail в цикле для тысяч адресатов создаёт дорогое количество отдельных передач: Windows открывает SMTP-соединение для каждого письма, Unix обычно запускает программу. Задержка HTTP-ответа и таймауты становятся проблемой раньше, чем синтаксис цикла. Записывайте задания в очередь и отправляйте ограниченным worker с согласованным транспортом.

Повторять нужно с пониманием результата. Если соединение оборвалось после принятия, автоматический немедленный retry может создать дубль. Сохраняйте устойчивый ID события/уведомления и политику повторов; учитывайте лимиты провайдера и отказ подписчика. sleep и задержки сами по себе не дают надёжную очередь и гарантию доставки.

Все функции категории Mail и связанные инструменты

Mail не предоставляет своих классов, ресурсов и набора специальных констант; основные настройки перечислены выше. IMAP/Mailparse — отдельные категории с иными задачами, а не скрытые режимы mail.

Практика: принять заявку даже при временном сбое почты

Спроектируйте три состояния: заявка сохранена, уведомление ожидает отправки, транспорт принял уведомление. Не превращайте отсутствие письма в отсутствие заявки. Начните с модели состояния, затем свяжите её с базой и worker.

<?php
declare(strict_types=1);

$request = ['id' => 17, 'saved' => true];
$notification = ['request_id' => 17, 'status' => 'pending', 'attempts' => 0];
$transportAccepted = false; // Модель отказа, сеть не вызывается.
$notification['attempts']++;
if ($transportAccepted) $notification['status'] = 'accepted';
echo $request['saved'] ? "Заявка сохранена\n" : "Заявка не сохранена\n";
echo $notification['status'], ':', $notification['attempts'], "\n";

Заявка сохранена
pending:1