Email¶

Основное использование¶

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

use Cake\Mailer\Email;

После того, как вы загрузили класс Email, вы можете сразу отправить электронное письмо следующим образом:

$email = new Email('default');
$email->from(['[email protected]' => 'My Site'])
    ->to('[email protected]')
    ->subject('About')
    ->send('My message');

Поскольку методы setter класса Email возвращают экземпляр класса, вы можете установить его свойства с помощью цепочки методов.

Email имеет несколько методов для определения получателей - to(), cc(), bcc(), addTo(), addCc() и addBcc(). Основное отличие состоит в том, что первые три будут перезаписывать то, что уже было установлено, а последние три просто добавят больше получателей в соответствующее поле:

$email = new Email();
$email->to('[email protected]', 'To Example');
$email->addTo('[email protected]', 'To2 Example');
// Получатели электронной почты: [email protected] and [email protected]
$email->to('[email protected]', 'ToTest Example');
// Получатель электронной почты: [email protected]

$email = new Email();
$email->sender('[email protected]', 'MyApp emailer');

Конфигурация¶

Конфигурация для Email по умолчанию создаётся с помощью config() и configTransport(). Вы должны поместить свои настройки электронной почты в файл config/app.php. Файл config/app.default.php является примером такого файла. Определять конфигурацию электронной почты в config/app.php не обязательно. Email можно использовать без config() и использовать соответствующие методы для установки всех конфигураций отдельно или загрузки массива конфигураций.

Определяя профили и транспорты, вы можете сохранить код приложения чистым, и избежать дублирования, чтобы не затруднять обслуживание и развертывание.

Чтобы загрузить предопределённую конфигурацию, вы можете использовать метод profile() или передать его конструктору Email:

$email = new Email();
$email->profile('default');

// Или в конструкторе
$email = new Email('default');

Вместо передачи строки, которая соответствует предварительно настроенному имени конфигурации, вы также можете просто загрузить массив параметров:

$email = new Email();
$email->profile(['from' => '[email protected]', 'transport' => 'my_custom']);

// Или в конструкторе
$email = new Email(['from' => '[email protected]', 'transport' => 'my_custom']);

use Cake\Mailer\Email;

// Пример настройки почты
Email::configTransport('default', [
    'className' => 'Mail'
]);

// Пример настройки SMTP
Email::configTransport('gmail', [
    'host' => 'ssl://smtp.gmail.com',
    'port' => 465,
    'username' => '[email protected]',
    'password' => 'secret',
    'className' => 'Smtp'
]);

use Cake\Mailer\Email;

Email::configTransport('gmail', [
    'host' => 'smtp.gmail.com',
    'port' => 587,
    'username' => '[email protected]',
    'password' => 'secret',
    'className' => 'Smtp',
    'tls' => true
]);

Email::configTransport('default', [
    'url' => 'smtp://[email protected]:[email protected]:587?tls=true',
]);

Настройка заголовков¶

В Email вы можете устанавливать любые заголовки, которые захотите. При переносе на использование электронной почты не забудьте поставить в свои заголовки префикс X-.

Смотрите Email::headers() и Email::addHeaders()

Отправка шаблонных писем¶

Электронная почта часто намного больше, чем просто текстовое сообщение. Чтобы облегчить это, CakePHP предоставляет способ отправки писем с использованием view layer.

Шаблоны для электронных писем хранятся в специальной папке в каталоге Template вашего приложения под названием Email. Представления электронной почты также могут использовать макеты и элементы, аналогичные нормальным представлениям:

$email = new Email();
$email
    ->template('welcome', 'fancy')
    ->emailFormat('html')
    ->to('[email protected]')
    ->from('[email protected]')
    ->send();

Вышеизложенное будет использовать src/Template/Email/html/welcome.ctp для представления и src/Template/Layout/Email/html/fancy.ctp для макета(лейаута). Вы также можете отправить многостраничные шаблонные сообщения электронной почты:

$email = new Email();
$email
    ->template('welcome', 'fancy')
    ->emailFormat('both')
    ->to('[email protected]')
    ->from('[email protected]')
    ->send();

Это будет использовать следующие файлы шаблонов:

• src/Template/Email/text/welcome.ctp

• src/Template/Layout/Email/text/fancy.ctp

• src/Template/Email/html/welcome.ctp

• src/Template/Layout/Email/html/fancy.ctp

При отправке шаблонных писем у вас есть возможность отправить либо text, html или both.

Вы можете установить переменные вида с помощью Email::viewVars():

$email = new Email('templated');
$email->viewVars(['value' => 12345]);

В шаблонах электронной почты вы можете использовать:

<p>Here is your value: <b><?= $value ?></b></p>

Вы также можете использовать Помощников в электронных письмах, как и в обычных файлах шаблонов. По умолчанию загружается только HtmlHelper. Вы можете загрузить дополнительные помощники с помощью метода helpers():

$email->helpers(['Html', 'Custom', 'Text']);

При настройке помощников обязательно укажите „Html“ или он будет удалён из помощников, загруженных в ваш шаблон электронной почты.

Если вы хотите отправить письмо с помощью шаблонов в плагине, вы можете использовать знакомый plugin syntax делая это так:

$email = new Email();
$email->template('Blog.new_comment', 'Blog.auto_message');

Вышеупомянутый пример будет использовать шаблон и макет из плагина Blog.

В некоторых случаях вам может потребоваться переопределить шаблон по умолчанию, предоставляемый плагинами. Вы можете сделать это с помощью Тем, указав Email для которого будет использоваться соответствующая тема, для этого используйте метод Email::theme():

$email = new Email();
$email->template('Blog.new_comment', 'Blog.auto_message');
$email->theme('TestTheme');

Это позволяет вам переопределить шаблон new_comment в своей теме, не изменяя плагин Blog. Файл шаблона должен быть создан по следующему пути: src/Template/Plugin/TestTheme/Plugin/Blog/Email/text/new_comment.ctp.

Отправка вложений¶

Cake\Mailer\Email::attachments($attachments)¶

Существует несколько разных форматов в зависимости от того, какие файлы у вас есть, и как вы хотите, чтобы имена файлов отображались в почтовом клиенте получателя:

1. Строка: $email->attachments('/full/file/path/file.png') будет прикреплять файл с именем file.png

2. Массив: $email->attachments(['/full/file/path/file.png']) будет иметь такое же поведение, как использование строки

3. Массив с ключом: $email->attachments(['photo.png' => '/full/some_hash.png']) будет прикреплён файл some_hash.png с именем photo.png. Получатель увидит photo.png, а не some_hash.png

4. Вложенные массивы:

   $email->attachments([
       'photo.png' => [
           'file' => '/full/some_hash.png',
           'mimetype' => 'image/png',
           'contentId' => 'my-unique-id'
       ]
   ]);
   

   Вышеприведённый файл будет прикреплён к файлу с другим типом mimetype и с пользовательским идентификатором содержимого (при установке ID идентификатора содержимого, которое будет приложением преобразовано во встроенный). Mimetype и contentId не являются обязательными в этой форме.

   4.1. Когда вы используете contentId, вы можете использовать этот файл в теле HTML, например <img src="cid:my-content-id">.

   4.2. Вы можете использовать опцию contentDisposition, чтобы отключить заголовок Content-Disposition для вложения. Это полезно при отправке ваших приглашений клиентам с использованием Outlook.

   4.3 Вместо параметра file вы можете предоставить содержимое файла в виде строки, используя опцию data. Это позволит вам прикреплять файлы, не требуя для них пути к файлам.

Использование транспорта¶

Транспорты - это классы, предназначенные для отправки электронной почты по некоторому протоколу или методу. CakePHP поддерживает сообщения Mail (по умолчанию), Debug и SMTP.

Чтобы настроить свой метод, вы должны использовать метод Cake\Mailer\Email::transport() или иметь транспорт в вашей конфигурации:

$email = new Email();

// Использовать именованный транспорт, уже настроенный с
// использованием электронной почты::configTransport()
$email->transport('gmail');

// Использовать построенный объект
$transport = new DebugTransport();
$email->transport($transport);

namespace App\Mailer\Transport;

use Cake\Mailer\AbstractTransport;
use Cake\Mailer\Email;

class ExampleTransport extends AbstractTransport
{
    public function send(Email $email)
    {
        // Тут что нибудь делаем
    }
}

$yourInstance = $email->getTransport()->transportClass();
$yourInstance->myCustomMethod();
$email->send();

$email = new Email('default');

// Сменить шаблон электронной почты, чтобы вы могли отправлять письма
    // на соответствующие адреса.
$email->emailPattern($newPattern);

Быстрая отправка сообщений¶

Иногда вам нужен быстрый способ отправить электронную почту, и вам не обязательно заранее устанавливать конфигурацию. Cake\Mailer\Email::deliver() предназначен для этой цели.

Вы можете создать свою конфигурацию, используя Cake\Mailer\Email::config(), или используйте массив со всеми необходимыми параметрами и используйте статический метод Email::deliver(). Например:

Email::deliver('[email protected]', 'Subject', 'Message', ['from' => '[email protected]']);

Этот метод отправит электронное письмо на адрес «you@example.com», от «me@example.com» с пометкой «Subject» и контентом «Message».

Возврат метода deliver() является экземпляром Cake\Mailer\Email со всеми установленными конфигурациями. Если вы не хотите отправлять электронную почту сразу и хотите настроить несколько вещей перед отправкой, вы можете передать 5-й параметр как false.

3ий параметр - это содержимое сообщения или массив с переменными (при использовании визуализированного содержимого).

4ым параметром может быть массив с конфигурациями или строка с именем конфигурации в Configure.

Если вы хотите, вы можете передать объект, тему и сообщение как null и выполнить все конфигурации в 4-м параметре (в виде массива или с помощью Configure). Проверьте список configurations, чтобы увидеть все доступные конфиги.

Отправка писем из CLI (командной строки)¶

При отправке писем в сценарии CLI (оболочки, задачи, …) вы должны вручную указать имя домена для использования электронной почты. Он будет служить именем хоста для идентификатора сообщения (поскольку в среде CLI нет имени хоста)

$email->domain('www.example.org');
// Результаты в идентификаторах сообщений, таких как ``<[email protected]>`` (валидный)
// Вместо `<UUID@>`` (не валидного)

Действительный идентификатор сообщения может помочь предотвратить попадание писем в папки спама.

Создание многоразовых писем¶

Mailers позволяют создавать повторно используемые письма во всём приложении. Они также могут использоваться для хранения нескольких конфигураций электронной почты в одном месте. Это помогает сохранить код DRY(чистым) и устраняет помехи конфигурации электронной почты из других областей вашего приложения.

В этом примере мы создадим Mailer, который содержит связанные с пользователем электронные письма. Чтобы создать наш UserMailer, создайте файл src/Mailer/UserMailer.php. Содержимое файла должно выглядеть следующим образом:

namespace App\Mailer;

use Cake\Mailer\Mailer;

class UserMailer extends Mailer
{
    public function welcome($user)
    {
        $this
            ->to($user->email)
            ->subject(sprintf('Welcome %s', $user->name))
            ->template('welcome_mail', 'custom'); // По умолчанию используется шаблон с тем же именем, что и имя метода.
    }

    public function resetPassword($user)
    {
        $this
            ->to($user->email)
            ->subject('Reset password')
            ->set(['token' => $user->token]);
    }
}

В нашем примере мы создали два метода: один для отправки приветственного сообщения, а другой - для отправки пароля для сброса пароля. Каждый из этих методов ожидает пользователя Entity и использует его свойства для настройки каждого электронного письма.

Теперь мы можем использовать наш UserMailer для отправки наших писем, связанных с пользователем, из любого места нашего приложения. Например, если мы хотим отправить приветственное письмо, мы можем сделать следующее:

namespace App\Controller;

use Cake\Mailer\MailerAwareTrait;

class UsersController extends AppController
{
    use MailerAwareTrait;

    public function register()
    {
        $user = $this->Users->newEntity();
        if ($this->request->is('post')) {
            $user = $this->Users->patchEntity($user, $this->request->getData())
            if ($this->Users->save($user)) {
                $this->getMailer('User')->send('welcome', [$user]);
            }
        }
        $this->set('user', $user);
    }
}

Если бы мы хотели полностью отделить отправку пользователю приветственного письма от кода нашего приложения, мы можем подписывать UserMailer на событие Model.afterSave. Подписавшись на мероприятие, мы можем полностью закрывать пользовательские классы нашего приложения, не связанные с электронной логикой и инструкциями, связанными с электронной почтой. Например, мы могли бы добавить следующее к нашему UserMailer:

public function implementedEvents()
{
    return [
        'Model.afterSave' => 'onRegistration'
    ];
}

public function onRegistration(Event $event, EntityInterface $entity, ArrayObject $options)
{
    if ($entity->isNew()) {
        $this->send('welcome', [$entity]);
    }
}

Теперь объект почтовой программы можно зарегистрировать как прослушиватель событий, а метод onRegistration() будет вызываться каждый раз, когда будет запущено событие Model.afterSave. Информацию о том, как регистрировать объекты прослушивателя событий, см. в документации registering-event-listeners.