<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.11 $ -->
 <reference id="ref.errorfunc">
  <title>エラー処理およびログ記録関数</title>
  <titleabbrev>エラーとログ記録</titleabbrev>

  <partintro>
   <para>
    以下の関数は、エラー処理およびログ記録を行います。これらの関数によ
    り、独自のエラー処理規則を定義することが可能になり、同時にエラーの
    ログを記録する方法を修正することが可能になります。これにより、ニー
    ズに即したエラー出力の変更と拡張が可能になります。
   </para>
   <para> 
    ログ記録関数により他のマシンやemail(またはポケベルのゲートウエイ
    に!)、システムログ等に直接メッセージを送信することが可能になります。
    これにより、ログを行うものを選択したり、アプリケーションやWebサイ
    トに最も重要な部分をモニタすることが可能になります。
   </para>
   <para> 
    エラー出力関数により、エラーのフィードバックのレベルと種類、
    簡単な通知からカスタマイズされた関数までエラーの際に返すもの
    をカスタマイズすることが可能になります。
   </para>
  </partintro>

  <refentry id="function.error-log">
   <refnamediv>
    <refname>error_log</refname>
    <refpurpose>エラーメッセージを送信する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>error_log</methodname>
      <methodparam><type>string</type><parameter>message</parameter></methodparam>
      <methodparam><type>int</type><parameter>message_type</parameter></methodparam>
      <methodparam><type>string</type><parameter>
	<replaceable><optional>destination</optional></replaceable>
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
	<replaceable><optional>extra_headers</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
    エラーメッセージを Web サーバのエラーログ、
    <acronym>TCP</acronym>ポート、ファイルのいずれかに送ります。
    最初のパラメータ <parameter>message</parameter> はログされる
    メッセージです。2 番目のパラメータ <parameter>message_type
    </parameter> はメッセージをどこへ送るのかを指定します。
     <table>
      <title><function>error_log</function> ログタイプ</title>
      <tgroup cols="2">
       <tbody>
	<row>
	 <entry>0</entry>
	 <entry>
	  <parameter>message</parameter> は、オペレーティング・システム
	  のシステムログのメカニズムまたはファイルのいずれかを使って
	  PHP のシステム・ロガーに送られます。どちらが使われるかは、
	  <link linkend="ini.error-log">error_log</link> の設定
	  ディレクティブにより決定されます。
	 </entry>
	</row>
	<row>
	 <entry>1</entry>
	 <entry>
	  <parameter>message</parameter> は、<parameter>destination
	  </parameter> パラメータで指定されたアドレスに、電子メール
	  により送られます。このメッセージタイプの場合にのみ、
	  4 番目のパラメータである <parameter>extra_headers</parameter>
	  が使われます。このメッセージタイプは、<function>mail</function>
	  と同様に、同じ名前の内部関数を使用します。
	 </entry>
	</row>
	<row>
	 <entry>2</entry>
	 <entry>
	  <parameter>message</parameter> は、PHP のデバッグ用コネクション
	  を通して送られます。このオプションは、
	  <link linkend="install.configure.enable-debugger">リモートデ
	  バッグが有効になっている</link>場合のみ使用できます。このケー
	  スでは、<parameter>destination</parameter> パラメータにより、
	  デバッグ情報を受け取るソケットのホスト名または IP アドレス、
	  およびオプションでポート番号を指定します。
	 </entry>
	</row>
	<row>
	 <entry>3</entry>
	 <entry>
	  <parameter>message</parameter> は <parameter>destination
	  </parameter> で指定されたファイルに追加されます。
	 </entry>
	</row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <warning>
     <para>
      TCP/IP経由でのリモートデバッグは、PHP 3の機能であり、PHP 4では利
      用できません。
     </para>
    </warning>
    <para>
     <example role="php">
      <title><function>error_log</function> の例</title>
      <programlisting role="php">
<![CDATA[
// データベースに接続できない場合、
// サーバログを通してエラーを通知する。
if (!Ora_Logon ($username, $password)) {
    error_log ("オラクルのデータベースが使用できません!", 0);
}

// Foo に失敗したら、管理者に email で通知する
if (!($foo = allocate_new_foo()) {
    error_log("大変です！ FOO に失敗しました!", 1,
              "operator@mydomain.com");
}

// これ以外の error_log() のコール方法：
error_log ("大変だ!", 2, "127.0.0.1:7000");
error_log ("大変だ!", 2, "loghost");
error_log ("大変だ!", 3, "/var/tmp/my-errors.log");
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.error-reporting">
   <refnamediv>
    <refname>error_reporting</refname>
    <refpurpose>出力するPHPエラーの種類を設定する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>error_reporting</methodname>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>level</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     PHP のエラー出力レベルを設定し、元のレベルを返します。
     エラー出力レベルは以下の値のビットマスクです（リンクをたどって
     もらうと、それらの意味を知るための内部値がわかります）。
     エラー報告レベル(error_reporting)はビットマスクまたは定数名のどち
     らかです。将来のバージョンとの互換性を保証するために定数名を使用
     することが強く推奨されます。エラーレベルが追加された場合、整数の
     範囲は増加するため、以前の整数を使用するエラーレベルは常に期待通
     りに動作するとは限りません。
     <example role="php">
      <title>エラー整数の変更</title>
      <programlisting role="php">
<![CDATA[
error_reporting(55);   // PHP 3 では E_ALL ^ E_NOTICE と等価

/* 一方、PHP 4 では、'55' は(E_ERROR | E_WARNING | E_PARSE |
E_CORE_ERROR | E_CORE_WARNING) を意味します */

error_reporting(2039); // PHP 4 では E_ALL ^ E_NOTICE と等価

error_reporting(E_ALL ^ E_NOTICE); // PHP 3 と 4 の両方で共通
]]>
      </programlisting>
     </example>
     これらの意味を得るために内部の値を以下に示します。
     <table>
      <title><function>error_reporting</function> ビット値</title>
      <tgroup cols="2">
       <thead>
	<row>
	 <entry>値</entry>
	 <entry>内部名</entry>
	</row>
       </thead>
       <tbody>
	<row>
	 <entry>1</entry>
	 <entry>
	  <link linkend="internal.e-error">E_ERROR</link>
	 </entry>
	</row>
	<row>
	 <entry>2</entry>
	 <entry>
	  <link linkend="internal.e-warning">E_WARNING</link>
	 </entry>
	</row>
	<row>
	 <entry>4</entry>
	 <entry>
	  <link linkend="internal.e-parse">E_PARSE</link>
	 </entry>
	</row>
	<row>
	 <entry>8</entry>
	 <entry>
	  <link linkend="internal.e-notice">E_NOTICE</link>
	 </entry>
	</row>
	<row>
	 <entry>16</entry>
	 <entry>
	  <link linkend="internal.e-core-error">E_CORE_ERROR</link>
	 </entry>
	</row>
	<row>
	 <entry>32</entry>
	 <entry>
	  <link
	  linkend="internal.e-core-warning">E_CORE_WARNING</link>
	 </entry>
	</row>
	<row>
	 <entry>64</entry>
	 <entry>
	  <link linkend="internal.e-compile-error">E_COMPILE_ERROR</link>
	 </entry>
	</row>
	<row>
	 <entry>128</entry>
	 <entry>
	  <link linkend="internal.e-compile-warning">E_COMPILE_WARNING</link>
	 </entry>
	</row>
        <row>
         <entry>256</entry>
         <entry>
          <link linkend="internal.e-user-error">E_USER_ERROR</link>
         </entry>
        </row>
        <row>
         <entry>512</entry>
         <entry>
          <link linkend="internal.e-user-warning">E_USER_WARNING</link>
         </entry>
        </row>
        <row>
         <entry>1024</entry>
         <entry>
          <link linkend="internal.e-user-error">E_USER_NOTICE</link>
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     <example role="php">
      <title><function>error_reporting</function> の例</title>
      <programlisting role="php">
<![CDATA[
error_reporting (0);
// 全てのレポートをオフにする

error_reporting (7); // 古い構文、 PHP 2/3
error_reporting (E_ERROR | E_WARNING | E_PARSE); // PHP 3/4の新しい構文
/* 簡単な実行エラーに適する  */

error_reporting (15); // 古い構文、 PHP 2/3
error_reporting (E_ERROR | E_WARNING | E_PARSE | E_NOTICE); // PHP 3/4の新しい構文
/* 初期化されたいない(または恐らくスペルミスの)変数を通知するコードを
   作成するのに適する */

error_reporting (63); // 古い構文、 PHP 2/3
error_reporting (E_ALL); // PHP 3/4の新しい構文
/* 全てのPHPエラーをリポート */
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.restore-error-handler">
   <refnamediv>
    <refname>restore_error_handler</refname>
    <refpurpose>
     以前のエラーハンドラ関数を回復する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>void</type><methodname>restore_error_handler</methodname>
      <void/>
     </methodsynopsis>
    <para>
     <function>set_error_handler</function>を使用してエラーハンドラ関
     数を変更した後、元のエラーハンドラ(組込またはユーザ定義関数)に戻
     すために使用されます。
    </para>
    <para>
     <function>error_reporting</function>,
     <function>set_error_handler</function>,
     <function>trigger_error</function>,
     <function>user_error</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.set-error-handler">
   <refnamediv>
    <refname>set_error_handler</refname>
    <refpurpose>
     ユーザ定義のエラーハンドラ関数を設定する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>string</type><methodname>set_error_handler</methodname>
      <methodparam><type>string</type><parameter>error_handler</parameter></methodparam>
     </methodsynopsis>
    <para>
     スクリプトのエラー処理を行うユーザ関数
     (<parameter>error_handler</parameter>)を設定します。定義済のエラー
     ハンドラまたはエラーの際に &false; を返します。この関数は、実行時の
     エラー処理をユーザが定義するために使用します。例えば、致命的なエ
     ラーを発生した場合や、ある条件のもとに
     (<function>trigger_error</function>を使用して)エラーを発生する必
     要がある場合にデータやファイルを消去する必要があるようなアプリケー
     ションがこの場合にあたります。
    </para>
    <para>
     ユーザ関数の引数は2つ、エラーコードとエラーを記述する文字列です。
     PHP 4.0.2 からオプションのパラメータが3つ追加されています。これら
     は、エラーが発生したファイル名、エラーが発生した行、発生したエラー
     のコンテキスト(エラーが発生した場所でのアクティブなシンボルテーブ
     ルを指す配列)です。
    </para>
    <para>
     以下の例では、エラーを発生することにより内部例外の処理を表示し、
     ユーザ定義関数によりこれを処理します。
     <example>
      <title>
       <function>set_error_handler</function>および
       <function>trigger_error</function>によるエラー処理
      </title>
      <programlisting role="php">
<![CDATA[
<?php

// ユーザエラー定数による再定義 - PHP4 のみ
define (FATAL,E_USER_ERROR);
define (ERROR,E_USER_WARNING);
define (WARNING,E_USER_NOTICE);

// このスクリプトのエラー出力レベルを設定
error_reporting (FATAL | ERROR | WARNING);

// エラーハンドラ関数
function myErrorHandler ($errno, $errstr, $errfile, $errline) {
  switch ($errno) {
  case FATAL:
    echo "<b>FATAL</b> [$errno] $errstr<br>\n";
    echo "  Fatal error in line ".$errline." of file ".$errfile;
    echo ", PHP ".PHP_VERSION." (".PHP_OS.")<br>\n";
    echo "Aborting...<br>\n";
    exit -1;
    break;
  case ERROR:
    echo "<b>ERROR</b> [$errno] $errstr<br>\n";
    break;
  case WARNING:
    echo "<b>WARNING</b> [$errno] $errstr<br>\n";
    break;
    default:
    echo "Unkown error type: [$errno] $errstr<br>\n";
    break;
  }
}

// エラー処理のテスト用関数
function scale_by_log ($vect, $scale) {
  if ( !is_numeric($scale) || $scale <= 0 )
    trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale",
      FATAL);
  if (!is_array($vect)) {
    trigger_error("Incorrect input vector, array of values expected", ERROR);
    return null;
  }
  for ($i=0; $i<count($vect); $i++) {
    if (!is_numeric($vect[$i]))
      trigger_error("Value at position $i is not a number, using 0 (zero)", 
        WARNING);
    $temp[$i] = log($scale) * $vect[$i];
  }
  return $temp;
}

// 定義したエラーハンドラを設定する
$old_error_handler = set_error_handler("myErrorHandler");

// エラーを発生します。まず、数値でない項目が混ざった配列を定義します。
echo "vector a\n";
$a = array(2,3,"foo",5.5,43.3,21.11);
print_r($a);

// 次に警告を発生するような2番目の配列を生成します。
echo "----\nvector b - a warning (b = log(PI) * a)\n";
$b = scale_by_log($a, M_PI);
print_r($b);

// 配列の代わりに文字列を渡しており、問題を発生します。
echo &quot;----\nvector c - an error\n&quot;;
$c = scale_by_log(&quot;not array&quot;,2.3);
var_dump($c);

// ゼロまたは負数の log が定義されないという致命的なエラーを発生します。
echo "----\nvector d - fatal error\n";
$d = scale_by_log($a, -2.5);

?>
]]>
      </programlisting>
     </example>
     このサンプルスクリプトを実行すると、出力は次のようになります。
     <informalexample>
      <programlisting>
<![CDATA[
vector a
Array
(
    [0] => 2
    [1] => 3
    [2] => foo
    [3] => 5.5
    [4] => 43.3
    [5] => 21.11
)
----
vector b - a warning (b = log(PI) * a)
<b>WARNING</b> [1024] Value at position 2 is not a number, using 0 (zero)<br>
Array
(
    [0] => 2.2894597716988
    [1] => 3.4341896575482
    [2] => 0
    [3] => 6.2960143721717
    [4] => 49.566804057279
    [5] => 24.165247890281
)
----
vector c - an error
<b>ERROR</b> [512] Incorrect input vector, array of values expected<br>
NULL
----
vector d - fatal error
<b>FATAL</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br>
  Fatal error in line 36 of file trigger_error.php, PHP 4.0.2 (Linux)<br>
Aborting...<br>
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     PHP の標準のエラーハンドラは完全にバイパスされることに注意して下
     さい。<function>error_reporting</function> の設定は影響せず、どの
     ような場合でもユーザが設定したエラーハンドラがコールされます。た
     だし、この場合でもハンドラで <function>error_reporting</function>
     のカレントの値を読み、適当に動作させることは可能です。エラーを発
     生した命令の前に <link
     linkend="language.operators.errorcontrol">@ エラー制御演算子
     </link> が付加されている場合、この値は 0 となることには注意を要し
     ます。
    </para>
    <para>
     ユーザハンドラ関数は、要すれば <function>die</function> をコール
     する責任があることにも注意を要します。エラーハンドラ関数がリター
     ンした場合、スクリプトの実行は、エラーを発生した命令の次の命令に
     継続されます。
    </para>
    <para>
     <function>error_reporting</function>,
     <function>restore_error_handler</function>,
     <function>trigger_error</function>,
     <function>user_error</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.trigger-error">
   <refnamediv>
    <refname>trigger_error</refname>
    <refpurpose>
     ユーザレベルのエラー/警告/通知メッセージを生成する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>void</type><methodname>trigger_error</methodname>
      <methodparam><type>string</type><parameter>error_msg</parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>error_type</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     ユーザエラーを発生するために使用され、組込のエラーハンドラまたは
     新しいエラーハンドラ(<function>set_error_handler</function>)とし
     て設定済のユーザ定義関数と組み合わせて使用されます。エラー型には
     E_USER 関連の定数のみが使用可能で、デフォルトは
     <constant>E_USER_NOTICE</constant>となっています。
    </para>
    <para>
     この関数は、実行時の例外に特定の応答を生成する必要がある場合に有
     用です。以下に例を示します。
     <informalexample>
      <programlisting>
<![CDATA[
if (assert ($divisor == 0))
   trigger_error ("Cannot divide by zero", E_USER_ERROR);
]]>
      </programlisting>
     </informalexample>
     <note>
      <para>
       より、詳細な例については、
       <function>set_error_handler</function> を参照下さい。
     </para>
     </note>
    </para>
    <para>
     <function>error_reporting</function>,
     <function>set_error_handler</function>,
     <function>restore_error_handler</function>, 
     <function>user_error</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.user-error">
   <refnamediv>
    <refname>user_error</refname>
    <refpurpose>
     ユーザレベルのエラー/警告/通知メッセージを発生する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>void</type><methodname>user_error</methodname>
      <methodparam><type>string</type><parameter>error_msg</parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>error_type</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     これは、<function>trigger_error</function>へのエイリアスです。
    </para>
    <para>
     <function>error_reporting</function>,
     <function>set_error_handler</function>,
     <function>restore_error_handler</function>, 
     <function>trigger_error</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>

 </reference>

<!-- 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:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->