php email
v1.0.5
電子メールを送信してキューに入れるためのオブジェクト指向の方法を提供します。
ユーザー登録やパスワードリセット機能など、ほぼすべてのプロジェクトで電子メールを送信する必要があります。送信される電子メールのほとんどは非常に簡単です。 PGP 暗号化などの高度な機能は必要ありません。このライブラリは、PHPMailer (基礎となるライブラリ) を設定せずにそのような電子メールを作成したり、複数の電子メールを送信したり、データベースにバックアップされたキューを使用して電子メールの送信を延期したりする方法を提供します。オブジェクト指向の方法。
特徴は次のとおりです。
EmailQueueオブジェクトにカプセル化します。このプロジェクトは GNU LGPL 3.0 に基づいてライセンスされています。
composer install technicalguru/email
ソースコードパッケージはGitHubリリースページからダウンロードできます。
構成の中心となるクラスはEmailConfigです。必要な情報がすべて含まれています。基本的な骨格から始めましょう。
use TgEmailEmailConfig;
$config = new EmailConfig();
$config->setTimezone('Europe/Berlin');
$config->setDefaultSender('John Doe <[email protected]>');
$config->setSubjectPrefix('[MyAppName] ');
$config->setDebugAddress('[email protected]');
上記の行は構成を作成し、タイムスタンプを作成する必要がある場合にEurope/Berlinタイムゾーンを使用するように指示します。これは主に、電子メールがキューに入れられ、タイムスタンプを記録する必要がある場合に必要です。この値はオプションであり、デフォルトはUTCです。
次に、デフォルトの送信者アドレスが構成されます。デフォルトの送信者は、送信される特定の電子メールに送信者アドレスが定義されていない場合に使用されます。電子メール アドレスの作成については、以下でさらに説明します。
件名のプレフィックスは、後で送信されるすべての電子メールで使用されます。件名にはこの文字列が接頭辞として付けられます。デフォルトはNULLで、件名は変更されません。
デバッグ アドレスは、テスト メールを送信する必要がある場合にのみ必要です。
SMTP サーバーがどこにあるかを伝える必要があります。これらの値を次のように設定します。
use TgEmailConfigSmtpConfig;
$host = 'smtp.example.com;
$port = 587;
$auth = TRUE;
$username = 'mySmtpUser';
$password = 'mySmtpPassword';
$secureOption = 'starttls';
$smtpConfig = new SmtpConfig($host, $port, $auth, $username, $password, $secureOption);
$config->setSmtpConfig($smtpConfig);
ほとんどのオプションは説明のとおりです。 $auth基礎となる PHPMailer に、指定されたユーザー資格情報で認証するかどうかを指示します。 $secureOption PHPMailerによって定義され、値smtpsまたはstarttlsを持ちます。詳細については、PHPMailer のドキュメントを参照してください。
すべてのプロパティはセッターを使用して設定できます。
use TgEmailConfigSmtpConfig;
$smtpConfig = new SmtpConfig();
$smtpConfig->setHost('smtp.example.com');
$smtpConfig->setPort(587);
// continue setup...
認証資格情報は、 technicalguru/utilsパッケージのTgUtilsAuthCredentialsProviderインターフェイスを使用して設定することもできます。
// Define here your provider
$provider = ...;
// Tell SMTP config
$smtpConfig->setCredentialsProvider($provider);
ここで、中心となるMailQueueオブジェクトを作成します。
use TgEmailEmailQueue;
$mailer = new EmailQueue($config);
最初の電子メールを送信する準備ができました。
セットアップが正しく機能しているかどうかをすばやく簡単に確認する方法があります。
$email = $mailer->createTestMail();
$rc = $mailer->send($email);
電子メールを送信するための最小要件を設定しました。
use TgEmailEmail;
$email = new Email();
$email
->setSubject('Hello World')
->addTo('[email protected]', 'John Doe')
->addBcc('[email protected]')
->setReplyTo('[email protected]')
->setBody(Email::TEXT, 'The text e-mail body')
->setBody(Email::HTML, '<p>The HTML e-mail body</p>');
// Will return FALSE when sending fails
$rc = $mailer->send($email);
それでおしまい。電子メールを送信するためにアプリケーション コードに必要なのは、上記のコード スニペットだけです。構成とセットアップは、インフラストラクチャ設定のどこかに埋め込む必要があります。
ファイルの添付や画像の埋め込みも簡単です。ファイルをファイルシステム上で利用可能かつ読み取り可能にしておく必要があります。
use TgEmailAttachment;
$myFile = new Attachment(Attachment::ATTACHED, 'file.pdf', NULL, '/local/path/to/file.pdf', 'application/pdf');
$myImage = new Attachment(Attachment::EMBEDDED, 'img.png', 'img1', '/local/path/to/img.png', 'image/png');
$email
->addAttachment($myFile)
->addAttachment($myImage);
埋め込み画像の 3 番目のパラメータに注意してください。 HTML メール内で一意の ID を定義し、次の方法で参照できます。
// Using the embedded image
$myHTML = '<img src="cid:img1">';
MailQueueすべての添付ファイルをファイル システム上にそのまま残します。ただし、電子メールを送信した後にファイルを削除したい場合もあります。コンストラクターは 2 つの追加引数を受け取ります。
$myFile = new Attachment(Attachment::ATTACHED, $filename, $cid, $path, $mimeType, TRUE, TRUE);
最初のブール値は、電子メールが正常に送信された後にファイルが削除されるようにトリガーします。 2 番目のブール値は、送信が失敗したときにファイルを削除できるかどうかを示します。これらのパラメータを使用すると、一時ファイルについて気にする必要がなくなります。特にキューイングと遅延送信に関してはそうです。
MailQueueいわゆるメール モードをサポートします。これらはメーラー オブジェクトに電子メールの一般的な扱い方を指示します。これは、セットアップをテストする場合、実際の電子メール アドレスがある環境 (ユーザー受け入れテスト環境など) にいる場合、または実際に電子メールを送信することがあまり意味がない場合に便利です。
次のモードが利用可能です。
EmailQueue::DEFAULT - これは通常の操作です。すべての電子メールは定義どおりに送信されます。EmailQueue::BLOCK - これにより、メールが送信されたり、キューに入れられたりすることがなくなります。戻りコードは常に TRUE です。EmailQueue::REROUTE - すべての電子メールは別のアドレス (通常は管理者または開発者のアドレス) に送信され、電子メールの定義された受信者は無視されます。EmailQueue::BCC - 電子メールは目的の受信者に送信されますが、追加のアドレスが BCC に設定されます。送信またはキューに追加されるすべての電子メールをブロックするのは非常に簡単です。
$mailer->setMailMode(EmailQueue::BLOCK);
同じメソッドを中央のEmailConfigオブジェクトで使用できます。
RerouteConfig構成をメイン構成に設定する必要があります。これは、構成オブジェクトを作成するときに事前に設定することも、メール モードを設定するときにまとめて設定することもできます。
use TgEmailConfigRerouteConfig;
// Create the config
$subjectPrefix = '[Rerouted]';
$recipients = array('[email protected]');
$rerouteConfig = new RerouteConfig($subjectPrefix, $recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::REROUTE, $rerouteConfig);
メイン構成でBccConfig構成を設定する必要があります。これは、構成オブジェクトを作成するときに事前に設定することも、メール モードを設定するときにまとめて設定することもできます。
use TgEmailConfigBccConfig;
// Create the config
$recipients = array('[email protected]');
$bccConfig = new BccConfig($recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::BCC, $bccConfig);
アプリケーション コードから直接電子メールを送信する場合の欠点の 1 つは、時間がかかることです。ユーザーは、アプリケーションからの応答を確認する前に、送信が完了するまで待つ必要があります。電子メールのキューイングは、送信が延期され (cron ジョブよりも望ましい)、ユーザーがアプリケーションの応答を迅速に受け取るための解決策です。
電子メールをキューに入れるには、 TgDatabaseDatabaseオブジェクトが必要です。そうしないと、電子メールをキューに入れようとしたときにEmailQueue例外をスローします。 Databaseオブジェクトの作成方法については、 TgDatabaseDatabaseドキュメントを参照してください。次のように、適切なEmailsDAOとEmailQueueをセットアップします。
use TgEmailEmailsDAO;
$dao = new EmailsDAO($database);
$mailer = new EmailQueue($config, $dao);
キューテーブルが存在しない場合、メーラーは自動的にキューテーブルを作成します。
EmailsDAOが利用可能になると、電子メールを簡単にキューに入れることができます。
// Create your email object here
$email = ...
// Queue it. Will return FALSE when sending fails
$rc = $mailer->queue($email);
別の呼び出しまたは cron ジョブ中にキューを処理できます。
$mailer->processQueue($maxSeconds);
引数$maxSeconds制限時間に達したときに処理が確実に停止されます。引数はオプションで、デフォルトは 60 秒です。
電子メール アドレスを作成するには複数の方法があります。すべてのメール コンポーネントはEmailAddressオブジェクトを使用します。電子メール アドレスが必要な場所であればどこでも、このオブジェクトを引数として使用できます。このようなオブジェクトを作成するには、いくつかの方法があります。
// From a string
$address = EmailAddress::from('[email protected]');
$address = EmailAddress::from('<[email protected]>');
$address = EmailAddress::from('John Doe <[email protected]>');
// From email string and name
$address = EmailAddress::from('[email protected]', 'John Doe');
// From another object
$obj = new stdClass;
$obj->name = 'John Doe';
$obj->email = '[email protected]';
$address = EmailAddress::from($obj);
// From another EmailAddress
$address = EmailAddress::from($anotherEmailAddressObject);
これは、電子メールを作成するときに次のフレーバーを使用できることを意味します。
$email->addTo('John Doe <[email protected]>');
$email->addTo('[email protected]', 'John Doe');
$email->addTo(array('John Doe <[email protected]>', $anotherEmailAddressObject, $obj);
上記で紹介した構成オブジェクトは、JSON 文字列、オブジェクト、または連想配列を使用して作成することもできます。次のスニペットは、短い表記で JSON オブジェクトを説明します。
SmtpConfig:
-----------
{
"host": "www.example.com",
"port": 587,
"debugLevel": 0,
"auth": true,
"secureOption": "starttls",
"charset": "utf8",
"credentials": {
"user": "username",
"pass": "password"
}
},
RerouteConfig:
--------------
{
"recipients": "[email protected]",
"subjectPrefix": "[Rerouted]"
},
BccConfig:
----------
{
"recipients": "[email protected]"
},
EmailConfig:
------------
{
"timezone": "Europe/Berlin",
"mailMode": "default",
"smtpConfig": {... see above ...},
"rerouteConfig": {... see above ...},
"bccConfig": {... see above ...},
"debugAddress": "[email protected]",
"defaultSender": "[email protected]",
"subjectPrefix": "[PHPUnitTest] "
}
各構成クラスは、これらの型を引数として受け取り、構成オブジェクト自体を返す静的from()メソッドを提供します。
$smtpConfig = SmtpConfig::from($jsonStringOrObjectOrAssocArray);
$rerouteConfig = RerouteConfig::from($jsonStringOrObjectOrAssocArray);
$bccConfig = BccConfig::from($jsonStringOrObjectOrAssocArray);
$emailConfig = EmailConfig::from($jsonStringOrObjectOrAssocArray);
Emailオブジェクトの配列をsend()とqueue()関数に渡すことができます。ただし、特に電子メールをすぐに送信する場合は、時間がかかる場合があることに注意してください。より良い戦略は、大量のメールをキューに入れることです。
利用可能な SMTP サーバーまたはデータベースがない場合、ほとんどの PHPUnit テストは実行されません。単体テストでは、環境変数EMAIL_TEST_SMTPおよびEMAIL_DATABASEをチェックします。これらの変数を作成する bash スクリプトset-test-env.shが利用可能です。これをset-local-test-env.shなどにコピーし、ファイル内の指示に従います。
GitHub Issue Tracker でバグを報告したり、機能拡張をリクエストしたり、プル リクエストを行ったりしてください。
