Email¶

基本的な使用法¶

まず最初に、クラスがロードされていることを確認する必要があります。

use Cake\Mailer\Email;

Email をロードしたら、次のようにメールを送信することができます。

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

Email のセッターメソッドは、クラスのインスタンスを返すので、 メソッド・チェーンでプロパティーを設定することができます。

Email は、受信者を定義するためのいくつかの方法があります - to() 、 cc() 、 bcc() 、 addTo() 、 addCc() そして addBcc() 。主な違いは最初の3つは、 すでに設定されていたものを上書きし、後者は単にそれぞれのフィールドに複数の受信者を追加することです。

$email = new Email();
$email->to('[email protected]', 'To Example');
$email->addTo('[email protected]', 'To2 Example');
// メールの To 受信者は [email protected] と [email protected]
$email->to('[email protected]', 'ToTest Example');
// メールの To 受信者は [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 はそのファイルの設定なしでも利用可能で、すべての構成を個別に設定したり、 設定の配列をロードするためのメソッドを使用することができます。

プロファイルおよびトランスポートを定義することにより、アプリケーションコードにおいて 設定データの自由を保ち、メンテナンスおよび配備をより困難にする重複を避けることができます。

あらかじめ定義された設定をロードするには、 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;

// サンプル Mail 設定
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 の中に、自由にヘッダーをセットできます。Email を使用する際、 独自のヘッダーにプレフィックスの X- をつけることを忘れないでください。

Email::headers() と Email::addHeaders() を参照してください。

テンプレートメールの送信¶

メールはしばしば単純なテキストメッセージを超えたものになります。それを容易にするために CakePHP は、 ビューレイヤー を使用してメールを送信することができます。

メールのテンプレートは、 あなたのアプリケーションの 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>あなたの値は次のとおりです: <b><?= $value ?></b></p>

メールでも普通のテンプレートファイルと同様にヘルパーを使用できます。 デフォルトでは、 HtmlHelper のみがロードされます。 helpers() メソッドを使うことで追加でヘルパーをロードできます。

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

ヘルパーを設定する時は、’Html’ を含めて下さい。そうしなければ、メールテンプレートにロードされません。

もし、プラグインの中でテンプレートを使用してメール送信したい場合、おなじみの プラグイン記法 を使います。

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

上記の例は、 Blog プラグインのテンプレートとレイアウトを使用しています。

いくつかのケースで、プラグインで用意されたデフォルトのテンプレートを上書きしたい場合があるかもしれません。 Email::theme() メソッドを使って適切なテーマを使用することを Email に伝えることによって行います。

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

これは、Blog プラグインを更新せずにあなたのテーマの new_comment テンプレートで上書きできます。 テンプレートファイルは、以下のパスで作成する必要があります: 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']) は、 photo.png というファイル名で some_hash.png ファイルを添付します。 受信者からは、some_hash.png ではなく photo.png として見えます。

4. ネストした配列:

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

   上記は、異なる mimetype と独自のコンテンツID を添付します (添付をインラインに変換する場合にコンテンツIDをセットします)。 mimetype と contentId はこの形式のオプションです。

   4.1. contentId を指定した時、HTML 内で <img src="cid:my-content-id"> のようにファイルを使用できます。

   4.2. 添付の Content-Disposition ヘッダーを無効にするために contentDisposition オプションを使用できます。これは、outlook を使って ical の招待状をクライアントに送る時に便利です。

   4.3. file オプションの代わりに data オプションを使うと、 ファイル本文を文字列として添付することができます。これは、ファイルパスを指定せずに 添付することができます。

トランスポートの使用¶

トランスポートは、様々なプロトコルや方法でメールを送信するために設計されたクラスです。 CakePHP は、 Mail (デフォルト)、 Debug と SMTP トランスポートをサポートします。

これらの送信方法を設定するためには、 Cake\Mailer\Email::transport() メソッドを使用するか、設定内で transport を指定する必要があります。

$email = new Email();

// 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 インスタンスです。 もし、メールを送信せず送信前に幾つか設定変更したい場合、第５引数に false をセットしてインスタンスを 取得してください。

第３引数には、メッセージの本文か、レンダリングされた本文を使用時には変数の配列を指定します。

第４引数は、設定の配列や Configure 内の設定名の文字列を指定します。

もしあなたが望むのなら、サブジェクトと本文に null をセットして、すべての設定を (配列か Configure を使用して) 第４引数で指定できます。 全ての設定を知るために 設定 一覧を確認してください。

CLI からのメール送信¶

シェルやタスクなどの CLI スクリプトでメールを送信するとき、Email に使用するドメイン名を セットしなければなりません。(ホスト名が CLI 環境にないとき) ドメイン名は、メッセージ ID のホスト名として使用されます。

$email->domain('www.example.org');
// メッセージ ID は ``<UUID@>`` (無効) の代わりに、
// ``<[email protected]>`` (有効) を返します。

正しいメッセージ ID は、迷惑メールフォルダーへ振り分けられることを防ぐのに役立ちます。

再利用可能なメールの作成¶

Mailer は、アプリケーション全体で再利用可能なメールを作成することができます。 また、一ヶ所に複数のメール設定を格納するために使用することができます。 これは、コードを 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]);
    }
}

この例では、2つのメソッドを作成しました。１つは、ウェルカムメールを送信するため、もう１つは、 パスワードのリセットメールを送信するためのものです。これらの各メソッドは、 ユーザー 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]);
    }
}

Mailer オブジェクトは、イベントリスナーとして登録され、 onRegistration() メソッドは Model.afterSave イベントが起こるたびに呼び出されます。イベントリスナーオブジェクトの 登録方法に関する情報は、 リスナーの登録 のドキュメントを参照してください。

メールのテスト¶

メールをテストするためには、テストケースに Cake\TestSuite\EmailTrait を追加します。 EmailTrait は、アプリケーションから送信されたすべてのメールに対して実行できる 一連のアサーションをテストケースに提供します。

EmailTrait をテストケースに追加すると、アプリケーションのすべてのメール転送が、 Cake\TestSuite\TestEmailTransport に置き換えられます。 このトランスポートは送信する代わりにメールを傍受し、それらに対してアサートすることを可能とします。

テストケースにトレイトを追加してメールのテストを開始します。

namespace App\Test\TestCase;

use Cake\TestSuite\EmailTrait;

class MyTestCase extends TestCase
{
    use EmailTrait;
}

アサーションメソッド¶

Cake\TestSuite\EmailTrait トレイトは次のアサーションを提供します。

// 期待した数のメールが送信されたことをアサート
$this->assertMailCount($count);

// メールが送信されていないことをアサート
$this->assertNoMailSent();

// アドレスに対してメールが送信されたことをアサート
$this->assertMailSentTo($address);

// アドレスからメールが送信されたことをアサート
$this->assertMailSentFrom($address);

// メールに期待した内容が含まれていることをアサート
$this->assertMailContains($contents);

// メールに期待したHTMLコンテンツが含まれていることをアサート
$this->assertMailContainsHtml($contents);

// メールに期待したテキストコンテンツが含まれていることをアサート
$this->assertMailContainsText($contents);

// メールにメールゲッター内の期待値が含まれていることをアサート（例："subject"）
$this->assertMailSentWith($expected, $parameter);

// 特定のインデックスのメールがアドレスに対して送信されたことをアサート
$this->assertMailSentToAt($at, $address);

// 特定のインデックスのメールがアドレスから送信されたことをアサート
$this->assertMailSentFromAt($at, $address);

// 特定のインデックスのメールに期待した内容が含まれていることをアサート
$this->assertMailContainsAt($at, $contents);

// 特定のインデックスのメールに期待したHTMLコンテンツが含まれていることをアサート
$this->assertMailContainsHtmlAt($at, $contents);

// 特定のインデックスのメールに期待したテキストコンテンツが含まれていることをアサート
$this->assertMailContainsTextAt($at, $contents);

// 特定のインデックスのメールにメールゲッター内の期待値が含まれていることをアサート（例："subject"）
$this->assertMailSentWithAt($at, $expected, $parameter);