Функция cot_mailPrepareAddress в Cotonti

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

Функция cot_mailPrepareAddress предназначена для подготовки адресов электронной почты для использования в заголовках письма, таких как "To", "From", "Cc", и других. Она может обрабатывать как строки, так и массивы адресов. В случае массива адресов функция корректно форматирует адреса с именами пользователей и проверяет их на валидность.

Код функции

/**
 * @param array<int, string[]|string>|string $address
 *   string - email address:
 *       [email protected]
 *       [email protected], [email protected]
 *       User <[email protected]>
 *       User <[email protected]>, Another User <[email protected]>
 *   array:
 *       [['[email protected]', 'User'], '[email protected]', 'User3 <[email protected]>'],
 *
 * @return string
 */
function cot_mailPrepareAddress($address)
{
    if (is_string($address)) {
        return $address;
    }

    if (!is_array($address)) {
        return '';
    }

    // $address = ['[email protected]', 'User']
    if (
        count($address) == 2
        && is_string($address[0])
        && is_string($address[1])
        && cot_check_email($address[0]) &&
        !cot_check_email($address[1])
    ) {
        $address[1] = mb_encode_mimeheader($address[1], 'UTF-8', 'B', "\n");
        return $address[1] . ' <' . $address[0] . '>';
    }


    $result = [];
    foreach ($address as $val) {
        if (is_string($val)) {
            $result[] = $val;
            continue;
        }
        $val[1] = mb_encode_mimeheader($val[1], 'UTF-8', 'B', "\n");
        $result[] = $val[1] . ' <' . $val[0] . '>';
    }

    if (empty($result)) {
        return '';
    }

    return wordwrap(implode(', ', $result), 70, "\r\n");
}

Параметры:

1. $address (array|string):

Строка: Ожидается строка, представляющая один или несколько email-адресов.

Пример:

"[email protected]"
"User <[email protected]>, Another User <[email protected]>"

Массив: Массив адресов, где каждый элемент может быть строкой или массивом, содержащим адрес и имя.

Пример:

[
    ['[email protected]', 'User'],
    '[email protected]',
    'User3 <[email protected]>'
]

Возвращаемое значение:
Строка: Форматированная строка с email-адресами, готовая для использования в заголовках письма.

Логика работы:

Если $address — строка:

Если это просто строка с адресом или несколькими адресами, функция возвращает её без изменений.

Если $address — массив:

Для каждого элемента массива:
Если элемент является строкой, добавляется в итоговый список.
Если элемент является массивом из двух элементов (email и имя), то имя кодируется с помощью mb_encode_mimeheader(), и результат возвращается в виде строки вида: "Имя <email>".

Результат:

Если после обработки есть несколько адресов, они объединяются в одну строку, разделенную запятыми, и возвращаются.
Если список пуст, возвращается пустая строка.

При необходимости строка с адресами будет разделена на несколько строк по 70 символов с использованием wordwrap().

Примеры:
Пример 1: Строка с одним адресом

$address = "[email protected]";
echo cot_mailPrepareAddress($address);
// Результат: "[email protected]"

Пример 2: Массив с адресами и именами

$address = [['[email protected]', 'User'], '[email protected]', 'User3 <[email protected]>'];
echo cot_mailPrepareAddress($address);
// Результат: "User <[email protected]>, [email protected], User3 <[email protected]>"

Пример 3: Массив с некорректным именем

$address = [['[email protected]', 'User'], ['[email protected]', '']];
echo cot_mailPrepareAddress($address);
// Результат: "User <[email protected]>, [email protected]"

Особенности:

Функция обрабатывает как простые строки, так и массивы с парами "email и имя".
Проверяет валидность email-адресов с помощью функции cot_check_email().
Кодирует имена с использованием mb_encode_mimeheader(), чтобы поддерживать правильную кодировку и избежать проблем с символами в имени получателя.
Заключение:
Функция cot_mailPrepareAddress полезна для правильной обработки и подготовки email-адресов в различных форматах. Это особенно важно при работе с различными получателями письма, включая использование имен и их корректное кодирование в заголовках сообщений.