Функция cot_mail в Cotonti

Описание функции cot_mail

Функция cot_mail используется для отправки электронных писем в системе. Она может работать как с использованием стандартной PHP-функции mail(), так и с кастомизированными методами доставки, если они определены в cot_mail_custom(). Эта функция поддерживает различные параметры для отправки письма, включая несколько получателей, темы, текста сообщения и дополнительных заголовков.

Код функции

/**
 * Sends mail with standard PHP mail().
 * If cot_mail_custom() function exists, it will be called instead of the PHP
 * function. This way custom mail delivery methods, such as SMTP, are
 * supported.
 *
 * @param array{
 *   to: array|string,
 *   from?: array|string,
 *   cc?: array|string,
 *   bcc?: array|string
 * }|string $toOrParams
 *   if string - recipient email:
 *       [email protected]
 *       [email protected], [email protected]
 *       User <[email protected]>
 *       User <[email protected]>, Another User <[email protected]>
 * [
 *  'to' => [['[email protected]', 'User'], '[email protected]', 'User3 <[email protected]>'],
 *  'from' => ['[email protected]', 'SiteTitle'] // (optional) Default value will be used if absent
 *  'cc' => [['[email protected]', 'User4'], '[email protected]', 'User6 <[email protected]>'], // (optional)
 *      Add more recipients
 *  'bcc' => [['[email protected]', 'User7'], '[email protected]', 'User9 <[email protected]>'], // (optional)
 *      Add hidden recipients
 * ]
 *
 * @param string $subject Subject
 * @param string $body Message body
 * @param string|array $additionalHeaders Additional Message headers
 * @param bool $customTemplate Use custom template
 * @param string $additionalParameters Additional parameters passed to sendmail
 * @return bool
 *
 * @see https://www.php.net/manual/en/function.mail.php
 * @see http://www.faqs.org/rfcs/rfc2822.html
 */
function cot_mail(
    $toOrParams,
    $subject,
    $body,
    $additionalHeaders = '',
    $customTemplate = false,
    $additionalParameters = '',
    $html = false
) {
    global $cfg, $cot_mail_senders;

    if (function_exists('cot_mail_custom')) {
        return cot_mail_custom(
            $toOrParams,
            $subject,
            $body,
            $additionalHeaders,
            $customTemplate,
            $additionalParameters,
            $html
        );
    }
    $ret = true;
    if (is_array($cot_mail_senders) && count($cot_mail_senders) > 0) {
        foreach ($cot_mail_senders as $func) {
            $ret &= $func($toOrParams, $subject, $body, $additionalHeaders, $additionalParameters, $html);
        }
        return $ret;
    }

    $to = $from = $fromName = $cc = $bcc = null;

    if (empty($toOrParams)) {
        return false;
    }

    if (is_string($toOrParams)) {
        $to = $toOrParams;
    } else {
        if (empty($toOrParams['to'])) {
            $toOrParams = ['to' => $toOrParams];
        }
        $to = cot_mailPrepareAddress($toOrParams['to']);
    }

    if (!empty($toOrParams['from'])) {
        if (is_string($toOrParams['from'])) {
            $from = $toOrParams['from'];
        } elseif (is_array($toOrParams['from'])) {
            $from = $toOrParams['from'][0];
            $fromName = $toOrParams['from'][1];
        }
    }

    if (!empty($toOrParams['cc'])) {
        $cc = cot_mailPrepareAddress($toOrParams['cc']);
    }

    if (!empty($toOrParams['bcc'])) {
        $bcc = cot_mailPrepareAddress($toOrParams['cc']);
    }

    if (isset(Cot::$cfg['email_from_address']) && !empty(Cot::$cfg['email_from_address'])) {
        $fromHeaderEmail = Cot::$cfg['email_from_address'];
    } else {
        // If admin email is on the same domain as site
        $tmp = explode('@', Cot::$cfg['adminemail']);
        if (!empty($tmp[1]) && $tmp[1] == Cot::$sys['domain']) {
            $fromHeaderEmail = Cot::$cfg['adminemail'];
        } else {
            $fromHeaderEmail = 'mail_sender@' . Cot::$sys['domain'];
        }
    }

    $fromHeaderName = !empty($fromName) ? $fromName : Cot::$cfg['maintitle'];
    $fromHeaderName = mb_encode_mimeheader($fromHeaderName, 'UTF-8', 'B', "\n");

    if (empty($from)) {
        $from = Cot::$cfg['adminemail'];
    }

    $headers = 'From: ' . $fromHeaderName . ' <' . $fromHeaderEmail . ">\r\n";
    if (!empty($from)) {
        if (!empty($fromName)) {
            $fromName = mb_encode_mimeheader($fromName, 'UTF-8', 'B', "\n");
            $headers .= 'Reply-To: ' . $fromName . ' <' . $from . ">\r\n";
        } else {
            $headers .= 'Reply-To: ' . $from . "\r\n";
        }
    }
    if (!empty($cc)) {
        $headers .= 'Cc: ' . $cc . "\r\n";
    }
    if (!empty($bcc)) {
        $headers .= 'Bcc: ' . $bcc . "\r\n";
    }

    $headers .= 'Message-ID: ' . md5(uniqid(microtime())) . '@' . $_SERVER['SERVER_NAME'] . "\r\n";

    $type_body = $html ? 'html' : 'plain';
    $headers .= 'Content-Type: text/' . $type_body . "; charset=UTF-8\r\n";
    $headers .= "Content-Transfer-Encoding: base64\r\n";

    if (!empty($additionalHeaders)) {
        if (is_array($additionalHeaders)) {
            foreach ($additionalHeaders as $key => $header) {
                $headers .= $key . ': ' . $header . "\r\n";
            }
        } else {
            $headers .= $additionalHeaders . "\r\n";
        }
    }

    $headers .= 'X-Mailer: Cotonti v.' .  Cot::$cfg['version'];

    if (!$customTemplate) {
        $body_params = array(
            'SITE_TITLE' => $cfg['maintitle'],
            'SITE_URL' => $cfg['mainurl'],
            'SITE_DESCRIPTION' => $cfg['subtitle'],
            'ADMIN_EMAIL' => $cfg['adminemail'],
            'MAIL_SUBJECT' => $subject,
            'MAIL_BODY' => $body
        );

        $subject_params = array(
            'SITE_TITLE' => Cot::$cfg['maintitle'],
            'SITE_DESCRIPTION' => Cot::$cfg['subtitle'],
            'MAIL_SUBJECT' => $subject
        );

        $subjectPrepared = cot_title(Cot::$cfg['subject_mail'], $subject_params, false);

        $bodyMail = Cot::$cfg['body_mail'];
        if ($html) {
            // Normalise to \n
            $bodyMail = str_replace(["\r\n", "\r"], "\n", $bodyMail);
            $bodyMail = str_replace("\n", "<br />\n", $bodyMail);
        }
        $bodyPrepared = cot_title($bodyMail, $body_params, false);
    } else {
        $subjectPrepared = $subject;
        $bodyPrepared = $body;
    }

    // Message body line should be separated with a CRLF (\r\n). Lines should not be larger than 70 characters.
    // (RFC 2822) http://www.faqs.org/rfcs/rfc2822.html
    // Normalise to \n
    $bodyPrepared = str_replace(["\r\n", "\r"], "\n", $bodyPrepared);
    // Now convert LE as needed
    $bodyPrepared = str_replace("\n", "\r\n", $bodyPrepared);
    //$bodyPrepared = wordwrap($bodyPrepared, 70, "\r\n");
    $bodyPrepared = base64_encode($bodyPrepared);

    $subjectPrepared = mb_encode_mimeheader($subjectPrepared, 'UTF-8', 'B', "\n");

    if (ini_get('safe_mode')) {
        mail($to, $subjectPrepared, $bodyPrepared, $headers);

    } else {
        if (empty($additionalParameters)) {
            $additionalParameters = '';
        }
        mail($to, $subjectPrepared, $bodyPrepared, $headers, $additionalParameters);
    }

    if (function_exists('cot_stat_inc')) {
        cot_stat_inc('totalmailsent');
    }

    /* === Hook === */
    foreach (cot_getextplugins('mail.send.done') as $pl) {
        include $pl;
    }
    /* ===== */

    return true;
}

Параметры функции cot_mail:

1. $toOrParams (array|string):
Если строка, то это адрес получателя (например, "[email protected]").
Если массив, то он может содержать:
to — список получателей (обязательный параметр).
from — адрес отправителя (необязательно).
cc — список получателей для копии (необязательно).
bcc — скрытые получатели (необязательно).

Пример:

$toOrParams = [
    'to' => ['[email protected]', '[email protected]'],
    'from' => ['[email protected]', 'Admin'],
    'cc' => ['[email protected]'],
    'bcc' => ['[email protected]']
];

2. $subject (string):
Тема письма.
3. $body (string):
Текст сообщения.
4. $additionalHeaders (string|array):
Дополнительные заголовки для сообщения. Может быть строкой или массивом заголовков.
5. $customTemplate (bool):
Если true, то используется пользовательский шаблон для письма (по умолчанию используется стандартный шаблон).
6. $additionalParameters (string):
Дополнительные параметры для функции отправки почты, например, для sendmail.
7. $html (bool):
Если true, то письмо будет отправлено как HTML.

Логика работы функции:

Проверка функции cot_mail_custom:

Если функция cot_mail_custom() существует, она будет вызвана вместо стандартной функции PHP mail(). Это позволяет использовать кастомные методы доставки почты (например, SMTP).

Подготовка получателей:

В случае, если параметры $toOrParams являются строкой, она интерпретируется как список получателей.
В случае массива to, cc, и bcc может быть передано несколько получателей в виде массива строк.

Подготовка заголовков:

Заголовки для письма формируются с учетом отправителя, получателей (Cc, Bcc) и других настроек.

Шаблоны письма:

Если параметр $customTemplate равен false, используется стандартный шаблон с данными о сайте и письме. В противном случае, используется тело и тема письма, переданные в функцию.

Отправка письма:

Письмо отправляется с помощью стандартной PHP-функции mail(). Заголовки и тело письма кодируются в соответствии с RFC 2822.
Плагин-система:

После отправки письма вызываются плагины (если они есть) через систему хуков, что позволяет расширить функциональность.

Пример использования функции cot_mail :

$to = [
    'to' => ['[email protected]', '[email protected]'],
    'from' => ['[email protected]', 'Admin'],
    'cc' => ['[email protected]'],
    'bcc' => ['[email protected]']
];

$subject = "Test Email";
$body = "This is a test email message.";

cot_mail($to, $subject, $body);

Примечания:

Многофункциональность: Функция поддерживает отправку писем нескольким получателям, добавление копий и скрытых копий, а также работу с кастомизированными методами доставки.
Безопасность и проверка: Перед отправкой письма проверяется существование получателей, а также настраивается правильная кодировка и разделители в теле письма.
Функция cot_mail является важной частью системы уведомлений и общения с пользователями в системе Cotonti.