archived-doc-ja/reference/mail/functions/mail.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d43f29f6a628996d1b7c3be487dcff39450146bf Maintainer: hirokawa Status: ready -->
<!-- CREDITS: takagi,mumumu -->
<refentry xml:id="function.mail" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>mail</refname>
  <refpurpose>メールを送信する</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>mail</methodname>
   <methodparam><type>string</type><parameter>to</parameter></methodparam>
   <methodparam><type>string</type><parameter>subject</parameter></methodparam>
   <methodparam><type>string</type><parameter>message</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>string</type></type><parameter>additional_headers</parameter><initializer>[]</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>additional_params</parameter><initializer>""</initializer></methodparam>
  </methodsynopsis>
  <para>
   メールを送信します。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>to</parameter></term>
     <listitem>
      <para>
       メールの受信者。
      </para>
      <para>
       <link xlink:href="&url.rfc;2822">RFC 2822</link> を満たす書式でなければ
       なりません。例えば以下のようなものです。
       <simplelist>
        <member>user@example.com</member>
        <member>user@example.com, anotheruser@example.com</member>
        <member>User &lt;user@example.com&gt;</member>
        <member>User &lt;user@example.com&gt;, Another User &lt;anotheruser@example.com&gt;</member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       送信するメールの表題。
      </para>
      <caution>
       <para>
        表題は <link xlink:href="&url.rfc;2047">RFC 2047</link>
        を満たすものでなければなりません。
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>message</parameter></term>
     <listitem>
      <para>
       送信するメッセージ。
      </para>
      <para>
       改行コードは CRLF (\r\n) となります。各行の長さは 70 文字を超えては
       いけません。
      </para>
      <caution>
       <para>
        （Windows のみ）PHP が SMTP サーバーと直接通信をする際、ピリオドから
        始まる行は無視されます。これを防ぐには、行頭のピリオドを
        ピリオド 2 つに置き換えてください。
        <programlisting role="php">
<![CDATA[
<?php
$text = str_replace("\n.", "\n..", $text);
?>
]]>
        </programlisting>
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_headers</parameter>（オプション）</term>
     <listitem>
      <para>
       メールヘッダの最後に挿入される <type>String</type> または <type>array</type>。
      </para>
      <para>
       通常、これは追加のヘッダ（From、Cc、Bcc）のために用いられます。
       複数のヘッダを追加する場合は CRLF（\r\n）で区切ります。
       外部からのデータを用いてヘッダを組み立てる際には、想定外のヘッダが注入されることを防ぐための処理が必要です。
      </para>
      <para>
       <type>array</type> が渡されると、キーがヘッダの名前となり、
       値がそれぞれのヘッダの値になります。
      </para>
      <note>
       <para>
        メールを送信する際には、<emphasis>必ず</emphasis> 
        <literal>From</literal> ヘッダが含まれていなければなりません。
        <parameter>additional_headers</parameter> パラメータで指定するか、
        あるいは &php.ini; にデフォルト値を指定します。
       </para>
       <para>
        指定しなかった場合は、以下のようなエラーメッセージが返ります
        <literal>Warning: mail(): "sendmail_from" not
        set in php.ini or custom "From:" header missing</literal> 。
        Windows では、SMTP経由で直接メールを送信する際は、
        <literal>From</literal> ヘッダを設定すると
        <literal>Return-Path</literal> も設定されます。
       </para>
      </note>
      <note>
       <para>
        メッセージが受信されなかった場合には、LF（\n）のみを使ってみてください。
        Unix の MTA の中には、自動的に LF を CRLF に変換してしまう
        もの (有名なところでは、<link xlink:href="&url.qmail;">qmail</link> など)
        があります（もし CRLF を利用していた場合、CR が重複してしまいます）。
        ただし、これは最後の手段です。というのも、これは
        <link xlink:href="&url.rfc;2822">RFC 2822</link> に違反しているからです。
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_params</parameter>（オプション）</term>
     <listitem>
      <para>
       パラメータ <parameter>additional_params</parameter> は、
       追加のフラグをコマンドラインオプションとしてメール送信プログラムに渡す際に使用可能です。
       メール送信プログラムは、設定オプション
       <literal>sendmail_path</literal> により設定されます。例えば、
       sendmail を使用する際に <literal>-f</literal> オプションを使って
       エンベロープの sender アドレスを設定する際に使用できます。
      </para>
      <para>
       このパラメータはコマンドの実行を防止するために内部的に <function>escapeshellcmd</function>
       によってエスケープされます。 <function>escapeshellcmd</function> はコマンドの実行を防止しますが、
       別のパラメータを追加することは許してしまいます。セキュリティ上の理由から、
       シェルコマンドへの望ましくないパラメータの追加を避けるために、
       ユーザーはこのパラメータを適切に処理することが推奨されます。
      </para>
      <para>
       <function>escapeshellcmd</function> が自動的に適用されるため、
       インターネット RFC でメールアドレスとして許可さているいくつかの文字を使用することができません。
       <function>mail</function> はそうした文字を許可しないため、プログラム中でそうした文字の使用が必須である場合、
       メール送信の代替手段（フレームワークやライブラリの使用など）が推奨されます。
      </para>
      <para>
       この方法でエンベロープの sender ヘッダ（-f）を設定する際は、
       'X-Warning' ヘッダが付加されないように Web サーバーの実行ユーザーを
       sendmail 設定に追加しておく必要があるかもしれません。
       sendmail を利用している場合、これは <filename>/etc/mail/trusted-users</filename>
       で設定します。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   メール送信が受け入れられた場合に &true; 、それ以外の場合に &false;
   を返します。
  </para>
  <para>
   メールの配送が受け入れられたかどうかが基準であることに注意しましょう。
   メールが実際にあて先に届いたかどうかでは「ありません」。
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.2.0</entry>
       <entry>
        <parameter>additional_headers</parameter> パラメータは、
        <type>array</type> も受け入れるようになりました。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>メールを送信する</title>
    <para>
     <function>mail</function> を用いて単純なメールを送信する。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// 本文
$message = "Line 1\r\nLine 2\r\nLine 3";

// 1 行が 70 文字を超える場合のため、wordwrap() を用いる
$message = wordwrap($message, 70, "\r\n");

// 送信する
mail('caffeinated@example.com', 'My Subject', $message);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>追加ヘッダを付加してメールを送信する</title>
    <para>
     基本ヘッダに加え、MUA に From および Reply-To アドレスを通知する。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$to      = 'nobody@example.com';
$subject = 'the subject';
$message = 'hello';
$headers = 'From: webmaster@example.com' . "\r\n" .
    'Reply-To: webmaster@example.com' . "\r\n" .
    'X-Mailer: PHP/' . phpversion();

mail($to, $subject, $message, $headers);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>追加のヘッダを <type>array</type> で指定してメールを送信する</title>
    <para>
     この例は、すぐ上の例と同じメールを送信します。
     しかし、追加のヘッダを配列で渡しています (PHP 7.2.0 以降で利用可能)
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$to      = 'nobody@example.com';
$subject = 'the subject';
$message = 'hello';
$headers = array(
    'From' => 'webmaster@example.com',
    'Reply-To' => 'webmaster@example.com',
    'X-Mailer' => 'PHP/' . phpversion()
);

mail($to, $subject, $message, $headers);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>追加のコマンドラインパラメータを指定してメールを送信する</title>
    <para>
     <literal>sendmail_path</literal> を用いてメールを送信する際に利用する
     追加パラメータとして、<parameter>additional_params</parameter>
     が用いられます。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
mail('nobody@example.com', 'the subject', 'the message', null,
   '-fwebmaster@example.com');
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>HTML メールを送信する</title>
    <para>
     <function>mail</function> を用いて HTML メールを送信することも可能です。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// 複数の受信者を指定
$to = 'johny@example.com, sally@example.com'; // カンマに注意

// 表題
$subject = 'Birthday Reminders for August';

// 本文
$message = '
<html>
<head>
  <title>Birthday Reminders for August</title>
</head>
<body>
  <p>Here are the birthdays upcoming in August!</p>
  <table>
    <tr>
      <th>Person</th><th>Day</th><th>Month</th><th>Year</th>
    </tr>
    <tr>
      <td>Johny</td><td>10th</td><td>August</td><td>1970</td>
    </tr>
    <tr>
      <td>Sally</td><td>17th</td><td>August</td><td>1973</td>
    </tr>
  </table>
</body>
</html>
';

// HTML メールを送信するには Content-type ヘッダが必須
$headers[] = 'MIME-Version: 1.0';
$headers[] = 'Content-type: text/html; charset=iso-8859-1';

// 追加のヘッダ
$headers[] = 'To: Mary <mary@example.com>, Kelly <kelly@example.com>';
$headers[] = 'From: Birthday Reminder <birthday@example.com>';
$headers[] = 'Cc: birthdayarchive@example.com';
$headers[] = 'Bcc: birthdaycheck@example.com';

// 送信する
mail($to, $subject, $message, implode("\r\n", $headers));
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <note>
    <para>
     HTML などの複雑な形式のメールを送信する場合は、PEAR パッケージ
     <link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link>
     を利用することを推奨します。
    </para>
   </note>
  </para>
 </refsect1>

 <refsect1 role="notes">    
  &reftitle.notes;
  <note>
   <para>
    Windows 環境での <function>mail</function> のSMTP実装は、sendmail の実装とは
    多くの点で違います。
    第一に、メッセージの生成にローカルのバイナリは使用せず、
    ソケットを通じて直接操作するだけです。
    これは <literal>MTA</literal> がネットワークソケットを listen している
    必要があるということを意味します（ローカルホスト、リモートマシン
    どちらでもかまいません）。
   </para>
   <para>
    第二に、
    <literal>From:</literal> や
    <literal>Cc:</literal>・
    <literal>Bcc:</literal>・
    <literal>Date:</literal> のようなカスタムヘッダは
    <literal>MTA</literal> では<emphasis role="strong">なく</emphasis>
    PHP によってパースされます。
   </para>
   <para>
    そのため、<parameter>to</parameter> 引数には
    &quot;Something &lt;someone@example.com&gt;&quot; 形式の
    メールアドレスを与えることはできません。
    MTA と通信する際に mail コマンドはこれを適切にパースできません。
   </para>
  </note>
  
  <note>
   <para>
    <function>mail</function> 関数は、大量のメールをループ内で送信するには
    向いていないことに注意しましょう。この関数は 1 通のメールを送信するたびに
    SMTP ソケットをいったん閉じて開きなおします。これは非効率的です。
   </para>
   <para>
    大量のメールを送信する場合は、
    <link xlink:href="&url.pear.package;Mail">PEAR::Mail</link> および
    <link xlink:href="&url.pear.package;Mail_Queue">PEAR::Mail_Queue</link>
    パッケージを参照ください。
   </para>
  </note>

  <note>
   <para>
    以下の RFC も有用です。
    <link xlink:href="&url.rfc;1896">RFC 1896</link>、
    <link xlink:href="&url.rfc;2045">RFC 2045</link>、
    <link xlink:href="&url.rfc;2046">RFC 2046</link>、
    <link xlink:href="&url.rfc;2047">RFC 2047</link>、
    <link xlink:href="&url.rfc;2048">RFC 2048</link>、
    <link xlink:href="&url.rfc;2049">RFC 2049</link> および
    <link xlink:href="&url.rfc;2822">RFC 2822</link>
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mb_send_mail</function></member>
    <member><function>imap_mail</function></member>
    <member><link xlink:href="&url.pear.package;Mail">PEAR::Mail</link></member>
    <member><link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->