メールライブラリ

Ziu 付属のメールライブラリです。
様々な送信方式(送信エンジン)に対応しており、メールの作成から送信までを簡単に操作できる機能を提供しています。

設定
使い方
テンプレートの作成
メソッドリファレンス

設定

メールライブラリを利用するための設定を行ないます。
設定からデータ取得までの簡単な流れを示します。

単体で利用の設定方法

本メールライブラリは、単体で使用することができます。

$config  = array(
    'engine'        => 'smtp-login', // SMTP-AUTH LOGIN認証
    'smtp_hostname' => 'sample.com', // HELO ドメイン
    'smtp_host'     => 'sample.com',
    'smtp_user'     => 'test_user',
    'smtp_pass'     => 'test_pass',
);
$em = new Email($config);

Ziu で利用の設定方法

Ziu での利用では、コンフィグでメールに関する定義を事前に行ないます。

オートロード (スタートロード)
_init/s01_prepare.php などのスタートロードファイルを用意し初期化処理を行ないます。
ヘルパー関数 lib() は常にシングルトンオブジェクトを返します。スタートロードで事前に初期化することで以降のモジュール処理ではメールライブラリの設定を共有することができます。

$em = lib('email')->config(array(
    'engine'        => 'smtp-login', // SMTP-AUTH LOGIN認証
    'smtp_hostname' => 'sample.com', // HELO ドメイン
    'smtp_host'     => 'sample.com',
    'smtp_user'     => 'test_user',
    'smtp_pass'     => 'test_pass',
));

設定項目

共通設定

ライブラリ全般の設定を行ないます。

項目	型	初期値	説明
mailer_name	string	Ziu	`X-Mailer` ヘッダーの名前を指定します。
internal_enc	string	UTF-8	サーバー側処理の文字コードを指定します。
template_dir	string	なし	テンプレートフォルダパスを指定します。
template_ext	string	php	テンプレートファイルの拡張子を指定します。
debug_path	string	なし	デバッグ出力ファイルパスを指定します。注1)
debug_mode	boolean	FALSE	デバッグ可否フラグを指定します。注1)
regex_email	string	注2)	メールアドレスチェックの正規表現を指定します。

注1) デバッグログの利用推奨
SMTP／POP3のソケット通信ログが出力されます。
送信エンジン(後述参照)が mail、sendmail 以外の場合は、デバッグログの出力を推奨します。

注2) regex_email メールアドレスの正規表現
初期値 : /^([a-z0-9\+_\-]+)(\.[a-z0-9\+_\-]+)*@([a-z0-9\-]+\.)+[a-z]{2,6}$/ix

送信設定

送信設定を行ないます。

項目	型	初期値	説明
engine	string	mail	送信エンジンを指定します。注)
sendmail	string	/usr/sbin/sendmail -oi -f %s -t	Sendmailパスを指定します。
safe_mode	boolean	FALSE	PHPセーフモードの可否フラグを指定します。
smtp_protocol	string	tcp	送信プロトコルを指定します。(`tcp`, `ssl` or `tls`)
smtp_hostname	string	なし	`HELO` ホスト名を指定します。
smtp_host	string	なし	送信サーバーを指定します。
smtp_user	string	なし	送信ユーザー名を指定します。
smtp_pass	string	なし	送信パスワードを指定します。
smtp_port	integer	25	送信ポート番号を指定します。

注) engine は7つのエンジンから指定することができます。

mail ― PHPメール関数を利用して送信します。
連携項目：safe_mode がTRUEの場合、mail() 関数での追加パラメータ(-fなど)が使用不可となります。
sendmail ― Sendmailコマンドを利用して送信します。
連携項目：sendmail
smtp ― SMTP送信を利用して送信します。(認証は不使用)
連携項目：smtp_hostname smtp_host
smtp-pop ― POP BEFORE SMTP送信を利用して送信します。
連携項目：smtp_hostname smtp_host POP認証設定
smtp-plain ― SMTP-AUTH認証(PLAIN認証)を利用して送信します。
連携項目：smtp_protocol smtp_hostname smtp_host smtp_user smtp_pass smtp_port
smtp-login ― SMTP-AUTH認証(LOGIN認証)を利用して送信します。
連携項目：smtp_protocol smtp_hostname smtp_host smtp_user smtp_pass smtp_port
smtp-cram ― SMTP-AUT認証(CRAM-MD5認証)を利用して送信します。
連携項目：smtp_protocol smtp_hostname smtp_host smtp_user smtp_pass smtp_port

POP認証設定

POP認証の設定を行ないます。送信エンジンに smtp-pop を指定した場合に使用します。

項目	型	初期値	説明
smtp_pop_proto	string	tcp	POP認証のプロトコルを指定します。(`tcp`, `ssl` or `tls`)
smtp_pop_host	string	なし	POP認証のサーバーを指定します。
smtp_pop_user	string	なし	POP認証のユーザー名を指定します。
smtp_pop_pass	string	なし	POP認証のパスワードを指定します。
smtp_pop_port	integer	110	POP認証のポート番号を指定します。
smtp_pop_expire	integer	300	POP認証のキャッシュ有効期限を秒で指定します。
smtp_pop_cache	string	なし	POP認証のキャッシュファイルパスを指定します。

ソケット通信設定

SMTP認証／POP認証でソケット通信を行う場合の設定を行ないます。

項目	型	初期値	説明
socket_timeout	integer	5	ソケット通信のタイムアウト値を秒で指定します。
stream_ssl_opts	array	注)	SSLよる暗号化通信の設定を指定します。

注) stream_ssl_opts の初期値
verify_peer => TRUE, // 証明書チェックフラグ
allow_self_signed => TRUE, // 自己証明許可フラグ
verify_peer_name => TRUE, // ドメインチェックフラグ
詳細については http://php.net/manual/ja/context.ssl.php を参照下さい。

メール生成設定

送信するメール文生成に関する設定を行ないます。

項目	型	初期値	説明
mime_charset	string	ISO-2022-JP	メールの文字コードを指定します。
mime_header_enc	string	B	ヘッダーののエンコード形式を指定します。(`Q` or `B`)
mime_string_enc	string	Q	メール本文のエンコード形式を指定します。(`Q` or `B`)
mime_7bitset	array	`array('ISO-2022-JP', 'US-ASCII')`	MIME文字コードの7ビットセットを指定します。指定以外は8ビットと認識します。
mime_message	string	This mail is a multipart format.	マルチパート形式を利用する際の標準文章を指定します。
html_multipart	boolean	TRUE	HTMLメールのマルチパート形式の利用フラグです。
newline	string	\r\n	メール文の改行を指定します。
separators	string	;,	メールアドレス複数指定のセパレータを指定します。
replacer	string	##	テンプレート内置換タグのクォート文字を指定します。

使い方

接続設定

送信エンジンによりそれぞれの初期設定を行ないます。

PHPメール関数を利用

lib('email')->config(array(
    'engine' => 'mail',
));

Sendmailコマンドを利用

lib('email')->config(array(
    'engine' => 'sendmail',
));

SMTP送信を利用(認証なし)

lib('email')->config(array(
    'engine' => 'smtp',
    'smtp_hostname' => 'sample.com',
    'smtp_host' => 'sample.com',
    // SMTP、POP3のソケット通信ログを出力 (利用推奨)
    'debug_mode' => TRUE,
    'debug_path' => '/tmp/email_debug.' . date('Ymd') . '.log',
));

POP BEFORE SMTP送信を利用

lib('email')->config(array(
    'engine' => 'smtp-pop',
    'smtp_hostname' => 'sample.com',
    'smtp_host' => 'sample.com',
    'smtp_pop_host' => 'sample.com',
    'smtp_pop_user' => 'pop_user',
    'smtp_pop_pass' => 'pop_pass',
    'smtp_pop_cache' => '/tmp/pop_sample_cache.txt',
));

SMTP-AUTH送信のPLAIN認証を利用(TLS利用)

lib('email')->config(array(
    'engine' => 'smtp-plain',
    'smtp_protocol' => 'tls',
    'smtp_hostname' => 'sample.com',
    'smtp_host' => 'sample.com',
    'smtp_user' => 'plain_user',
    'smtp_pass' => 'plain_pass',
));

SMTP-AUTH認証は、smtp-login、smtp-cram も同様の設定です。プロトコルは環境ごとに ssl、tls、tcp から指定します。(デフォルト tcp)

メール送信

メール生成から送信までを行ないます。

テンプレート設定

$em = lib('email')->config(array(
    'template_dir' => '/path/to/template/email',
));

$em->template('thanks', array(
    'company_name' => $company_name,
    'signature' => $signature,
));

テンプレートフォルダパスを指定し、template メソッドでテンプレート名を指定しています。
第2引数にPHP変数をバインドしテンプレートファイル内で使用することができます。

テンプレートファイル

テキストメールのテンプレートとして「thanks.text.php」を用意します。
/path/to/template/email/thanks.text.php

subject: 【<?= $company_name ?>】運営事務局より テストメール送信

こんにちは ##nickname## さん
こちらは【<?= $company_name ?>】運営事務局です。

テストメールを送信します。
よろしくお願いします。

-- 
<?= $signature ?>

ヘッダー情報「subject:」とメール本文の間に 空行を入れる(\n\n) 必要があります。

ヘッダー情報の設定

送信者情報を指定します。

$em->return_path('test_system@sample.com');
$em->from('"運営事務局" <test_from@sample.com>');
$em->reply_to('"サポート窓口" <test_support@sample.com>');

件名も subject() メソッドで指定することができます。(例ではテンプレートファイルを利用)

キーワード置換

件名／メール本文に対してキーワード置換をすることができます。

$em->keyword(array('nickname' => $nickname))->replace();

キーワードは replacer 設定項目で指定されているクォート文字で囲み指定します。例では ##nickname## でテンプレート内に記載します。

送信者指定とメール送信

宛先情報を指定して送信します。

$em->to('"ユーザー様" <test_to@user.com>')->send();

送信者情報のクリア

送信が終わった後、次の送信に向けクリーニングします。

$em->clear('to')->clear('keyword')->clear('header');

上記例では宛先に関する情報のみクリーニングしています。

テンプレートの作成

メールライブラリのテンプレートファイルの作成方法について説明します。

ファイル名のルール
テンプレートファイルは拡張子 php で作成し、かつ3つのサフィックス head、html、text ファイルが定義できます。
ファイルは下記の順にロードされます。

(テンプレート名).head.php - ヘッダー情報のみ定義できます。HTML/TEXTメールの共通ヘッダー定義で利用します。
(テンプレート名).html.php - ヘッダー情報、HTMLメー本文を指定できます。
(テンプレート名).text.php - ヘッダー情報、TEXTメー本文を指定できます。

ヘッダー情報は全体で共有され、単一指定のヘッダー(return-path、from、reply-to、subject)が重複している場合は上書きされ後者が優先されます。

テンプレートの記述方法
テンプレートファイルは、ヘッダー情報とメール本文をそれぞれのサフィックスごとに記述することができます。
ヘッダー情報とメール本文の間には必ず 空行を入れる(\n\n) 必要があります。(text、htmlのみ)

(ヘッダー情報)
← 空行を1行入れる(\n\n)
(メール本文)

ヘッダー情報の定義
メールヘッダーとして以下のヘッダー情報を定義することができます。

ヘッダー	指定方法	指定数	説明
return-path	シンプル指定	単一	`Return-Path` ヘッダーとしてメールアドレスを1つ指定することができます。
reply-to	ラベル指定	単一	`Reply-To` ヘッダーとしてメールアドレスを1つ指定することができます。
from	ラベル指定	単一	`From` ヘッダーとしてメールアドレスを1つ指定することができます。
to	ラベル指定	複数	`To` ヘッダーとしてメールアドレスを複数指定することができます。
cc	ラベル指定	複数	`Cc` ヘッダーとしてメールアドレスを複数指定することができます。
bcc	ラベル指定	複数	`Bcc` ヘッダーとしてメールアドレスを複数指定することができます。
subject	文字列	単一	件名を指定することができます。キーワード／バインド変数指定可能。

メールアドレスはシンプル指定／ラベル指定ができ、複数対応の場合はカンマ又はセミコロンで複数記述することができます。

シンプル指定 : test@sample.com または <test@sample.com>
ラベル指定 : "テスト" <test@sample.com>、テスト <test@sample.com>、テスト test@sample.com のいづれか

記述例

return-path: system@sample.com
from: "運営事務局" <info@sample.com>
to: taro@user.com
subject: 運営事務局からのお知らせ

##nickname## さまへ

いつもご利用ありがとうございます。
「<?= $company_name ?>」運営事務局からのお知らせです。

...

メール本文の定義
TEXTメール本文にはそのまま文章を記述し、HTMLメール本文ではHTMLタグを記述します。
HTMLメールに画像を挿入する場合 <img> タグでファイルパスを指定し attachment() メソッドの第2引数の $disp を inline することで利用できます。

<img src="/path/to/image/sample.jpg" />

$em->attachment('/path/to/image/sample.jpg', 'inline');

メソッドリファレンス

メールライブラリのメソッドリファレンスです。

設定メソッド
- config() : 初期設定
- clear() : メール情報のクリーニング
メール情報メソッド
- subject() : 件名の指定
- body() : 本文の指定
- return_path() : Return-Path の指定
- reply_to() : Reply-To の指定
- from() : From の指定
- to() : To の指定
- cc() : Cc の指定
- bcc() : Bcc の指定
- attachment() : 添付ファイルを指定
- template() : テンプレートを指定
- header() : 追加ヘッダーを指定
置換キーワードメソッド
- keyword() : キーワードを指定
- replace() : キーワードで置換
送信メソッド
- send() : メールを送信
- open() : SMTPコネクションを作成
- push() : SMTPコネクションにメール送信
- close() : SMTPコネクションに切断

設定メソッド

config(array $config)

メールライブラリの初期設定をします。

戻り値

型 : object Email

引数値

項目	型	内容
$config	array	設定を配列で指定

$config に指定する設定項目については、設定を参照して下さい。

例) lib('email')->config(array('engine' => 'sendmail'));

clear($name = FALSE)

メール送信情報をクリーニングします。

戻り値

型 : object Email

引数値

項目	型	内容
$name	string	クリーニング対象名

$name に指定できる対象名
アドレス情報 : return-path / reply-to / from / to / cc / bcc
件名本文情報 : subject / body
ヘッダー情報 : header
ファイル情報 : attachment
キーワード情報 : keyword

例) $em->clear('to')->clear('keyword')->clear('header');

▲リファレンスTOP

メール情報メソッド

subject($str)

件名を指定します。

戻り値

型 : object Email

引数値

項目	型	内容
$str	string	メール件名

例) $em->subject('事務局からのお知らせ');

body($text, $html = FALSE)

メール本文を指定します。

戻り値

型 : object Email

引数値

項目	型	内容
$text	string	TEXTメール本文
$html	string	HTMLメール本文

例) $em->body("こんにちは\n\nテストメールを送信します。");

return_path($str)

Return-Path ヘッダーを指定します。

戻り値

型 : object Email

引数値

項目	型	内容
$str	string	メールアドレス

例) $em->return_path('system@sample.com');

reply_to($str)

Reply-To ヘッダーを指定します。

戻り値

型 : object Email

引数値

項目	型	内容
$str	string	メールアドレス

例) $em->reply_to('support@sample.com');

from($str, $label = '')

From ヘッダーを指定します。

戻り値

型 : object Email

引数値

項目	型	内容
$str	string	メールアドレス
$label	string	名前

例) $em->from('info@sample.com', '運営事務局');

to($str, $label = '')

To ヘッダーを指定します。

戻り値

型 : object Email

引数値

項目	型	内容
$str	string	メールアドレス
$label	string	名前

$str はカンマ、又はセミコロン区切りで複数指定可能です。
$label はメールアドレスを単指定でのみ使用できます。

例) $em->to('yamamoto@sample.com', '山本');

cc($str, $label = '')

Cc ヘッダーを指定します。

戻り値

型 : object Email

引数値

項目	型	内容
$str	string	メールアドレス
$label	string	名前

$str はカンマ、又はセミコロン区切りで複数指定可能です。
$label はメールアドレスを単指定でのみ使用できます。

例) $em->cc('"佐藤" sato@sample.com, "加藤" kato@sample.com');

bcc($str, $label = '')

Bcc ヘッダーを指定します。

戻り値

型 : object Email

引数値

項目	型	内容
$str	string	メールアドレス
$label	string	名前

$str はカンマ、又はセミコロン区切りで複数指定可能です。
$label はメールアドレスを単指定でのみ使用できます。

例) $em->bcc('"藤原" fujiwara@sample.com, "渡辺" watanabe@sample.com');

attachment($file, $disp = 'attachment')

添付ファイルを指定します。
TEXTメールでは、添付ファイルとして扱われます。
HTMLメールに挿入する場合 <img> タグでファイルパスを指定し$disp を inline することで利用できます。

戻り値

型 : object Email

引数値

項目	型	内容
$file	mixed	ファイルパス
$disp	string	添付ファイル `Content-Disposition` ヘッダー値

$file は配列で複数指定することができます。

例) $em->attachment(array('/path/to/file1.jpg', '/path/to/file2.jpg'));

template($name, $vars = array())

テンプレート名を指定します。
テンプレートに関する詳しい内容はテンプレートの作成を参照して下さい。

戻り値

型 : object Email

引数値

項目	型	内容
$name	string	テンプレート名
$vars	array	バインド変数

例) $em->template('thanks', array('company_name' => $company_name));

header($header)

追加ヘッダー情報を指定します。

戻り値

型 : object Email

引数値

項目	型	内容
$header	mixed	ヘッダー情報

$header 配列で複数指定することができます。

例) $em->header(array('X-Checker' => 'OK', 'X-Page' => 12));

▲リファレンスTOP

置換キーワードメソッド

keyword(array $set)

件名／メール本文で置換するキワードを指定します。
重複指定した場合は後者が優先されます。

戻り値

型 : object Email

引数値

項目	型	内容
$set	array	キーワードセット

例) $em->keyword(array('nickname' => $nickname));

replace(array $set = array())

キーワード置換を実行します。
keyword() メソッドと同様にキーワードを指定することができます。

戻り値

型 : object Email

引数値

項目	型	内容
$set	array	キーワードセット

例) $em->keyword(array('nickname' => $nickname))->replace();

▲リファレンスTOP

送信メソッド

send($engine = FALSE, $mailtype = FALSE)

メールを送信します。

戻り値

型 : boolean

引数値

項目	型	内容
$engine	string	送信エンジン
$mailtype	string	送信メールタイプ

$engine で初期設定とは別に強制的に送信エンジンを指定することができます。(デバッグ等で利用)
$mailtype も同様に送信メールタイプを強制的に指定できます。(通常は自動判定)

送信メールタイプ
text : TEXTメール
html : HTMLメール
text-attach : TEXT添付ファイルメール
html-attach : HTML添付ファイルメール

例) $em->send();

open($engine = FALSE, $mailtype = FALSE)

SMTPコネクションを作成します。
このメソッドは送信エンジンがSMTP系の場合のみ利用でき、push()、close() とセットで使用します。
連続で複数回メール送信する場合に、SMTPコネクションのオーバーヘッドを軽減する場合に用います。

戻り値

型 : void

引数値

項目	型	内容
$engine	string	送信エンジン
$mailtype	string	送信メールタイプ

$engine、$mailtype については send() メソッドを参照して下さい。

例) $em->open();

push()

open() メソッドで接続済みのSMTPコネクションを利用してメールを送信します。

戻り値

型 : boolean

引数値

なし

例) $em->push();

close()

open() メソッドで接続済みのSMTPコネクションを切断します。

戻り値

型 : void

引数値

なし

例) $em->close();

▲リファレンスTOP

メール ライブラリ

設定

単体で利用の設定方法

Ziu で利用の設定方法

共通設定

送信設定

POP認証設定

ソケット通信設定

メール生成設定

使い方

接続設定

メール送信

テンプレートの作成

メソッドリファレンス

設定メソッド

戻り値

引数値

戻り値

引数値

メール情報メソッド

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

置換キーワードメソッド

戻り値

引数値

戻り値

引数値

送信メソッド

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

メールライブラリ