cvs: peardoc /ja/package/html/html-css errorhandler.xml

http://cvs.php.net/viewvc.cgi/peardoc/ja/package/html/html-css/errorhandler.xml?view=markup&rev=1.1
Index: peardoc/ja/package/html/html-css/errorhandler.xml
+++ peardoc/ja/package/html/html-css/errorhandler.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.4 Maintainer: takagi Status: ready -->
<refentry id="package.html.html-css.errorhandler">
 <refnamediv>
  <refname>エラーハンドラ</refname>
  <refpurpose>柔軟なエラーハンドラプラグインシステム</refpurpose>
 </refnamediv>

 <refsect1 id="package.html.html-css.errorhandler.init">
  <title>導入</title>
   <para>
    HTML_CSS パッケージには、柔軟なエラーハンドラプラグインシステムが組み込まれており、
    お好みのエラーハンドラを使用することができます。
    <classname>PEAR_Error</classname> オブジェクト (デフォルト) 以外にも
    <classname>PEAR_ErrorStack</classname> パッケージや
    その他のエラーハンドラをプラグインすることができます。
   </para>

   <para>
    何も設定をしなければ、HTML_CSS の API で発生したエラー (普通のエラーや例外)
    は <classname>HTML_CSS_Error</classname> オブジェクトを生成して呼び出し元
    (ユーザスクリプト) に返します。
    <tip>
     <para>
      他の PEAR パッケージが出した PEAR_Error と HTML_CSS のエラーを区別する簡単な方法は
      <methodname>HTML_CSS::isError()</methodname> です。
      また、エラーのレベル (警告、エラー、例外) を取得するには
      <methodname>HTML_CSS_Error::getLevel()</methodname> メソッドを使用します。
     </para>
    </tip>
   </para>

   <para>
    使い慣れた PEAR のエラー処理用 API も使えます。
    <programlisting role="php">
     <![CDATA[
<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$result = $css->setStyle('div', 'color', 5);
if (PEAR::isError($result)) {
    // 何らかのエラー処理
}
?>
     ]]>
    </programlisting>
    出力結果は、このようになるでしょう。
   </para>

   <informalexample>
     <screen>
Exception<co id="package.html.html-css.errorhandler.error.1.level"/>: invalid input, parameter #3 "$value" was expecting "string",
instead got "integer"<co id="package.html.html-css.errorhandler.error.1.message"/> in html_css->setstyle (file [path_to]\[filename] on line 6)<co id="package.html.html-css.errorhandler.error.1.context"/>
     </screen>
     <calloutlist>
      <callout arearefs="package.html.html-css.errorhandler.error.1.level">
       <para>
        エラーレベル
       </para>
      </callout>
      <callout arearefs="package.html.html-css.errorhandler.error.1.message">
       <para>
        メッセージ本文とコンテキスト情報
       </para>
      </callout>
      <callout arearefs="package.html.html-css.errorhandler.error.1.context">
       <para>
        呼び出しコンテキスト
       </para>
      </callout>
     </calloutlist>
   </informalexample>

   <para>
    この標準の挙動では不満があるかもしれませんが、心配無用です。
    すべてを変更することができます。
    <itemizedlist>
     <listitem>
      <simpara>エラーを表示するか無視するか</simpara>
     </listitem>
     <listitem>
      <simpara>メッセージの一部 (エラーレベル、本文、コンテキスト) の表示/非表示</simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    <important>
     <para>
      HTML_CSS は、
      <ulink url="&url.php;manual/en/ref.errorfunc.php#ini.display-errors">display_errors</ulink>
      および
      <ulink url="&url.php;manual/en/ref.errorfunc.php#ini.log-errors">log_errors</ulink>
      のプロトコルに従っています。
     </para>
    </important>
   </para>
 </refsect1>

 <refsect1 id="package.html.html-css.errorhandler.conf">
   <title>ハンドラの設定</title>
   <simpara>
    エラーハンドラを設定するには、コンストラクタの引数を使用します。
    パラメータの概要を、以下に示します。
   </simpara>

   <programlisting role="php">
    <![CDATA[
<?php
require_once 'HTML/CSS.php';

$errorConf = array('error_handler' => 'myErrorHandler',
                   'push_callback' => 'myError',
                   // ... その他のオプション
                  );
$css = new HTML_CSS(null, $errorConf);
?>
    ]]>
   </programlisting>

   <para>
    <table><title>エラーハンドラの設定パラメータ</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>オプション</entry>
        <entry>型</entry>
        <entry>説明</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>error_handler</entry>
        <entry>callback</entry>
        <entry>
         <methodname>HTML_CSS::raiseError()</methodname>
         メソッドが実行するエラー処理用のコールバック (関数)。
         デフォルトは <methodname>HTML_CSS::_errorHandler</methodname>。
        </entry>
       </row>
       <row>
        <entry>push_callback</entry>
        <entry>callback</entry>
        <entry>
         以下のアクションを決定するコールバック (関数)。
         デフォルトの返り値は、例外の場合は <constant>PEAR_ERROR_DIE</constant>、
         それ以外の場合は <constant>NULL</constant>。
        </entry>
       </row>
       <row>
        <entry>error_callback</entry>
        <entry>callback</entry>
        <entry>
         後始末用のユーザ関数をコールすることを決定するコールバック (関数)。
         デフォルトは、なし。
        </entry>
       </row>
       <row>
        <entry>message_callback</entry>
        <entry>callback</entry>
        <entry>
         メッセージの生成を制御するコールバック (関数)。
         デフォルトは <methodname>HTML_CSS_Error::_msgCallback</methodname>。
        </entry>
       </row>
       <row>
        <entry>context_callback</entry>
        <entry>callback</entry>
        <entry>
         エラーコンテキストの生成を制御するコールバック (関数)。
         デフォルトは <methodname>HTML_CSS_Error::getBacktrace</methodname>。
        </entry>
       </row>
       <row>
        <entry>handler</entry>
        <entry>mixed</entry>
        <entry>
         ハンドラ固有の設定。
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
  </refsect1>

  <refsect1 id="package.html.html-css.errorhandler.control">
   <title>エラーの発生の制御</title>
   <simpara>
    より綿密なエラー処理が必要となる場面も多々あります。
   </simpara>

   <para>
    エラーの発生を制御する第一段階は、&php.ini; の設定項目
    <emphasis>display_errors</emphasis> と <emphasis>log_errors</emphasis> です。
    これらを &true; にすると、それぞれブラウザ向けとファイル向けの出力が有効になります。
   </para>

   <para>
    <tip>
     <para>
      すべてのエラーを無視したい (画面にもログファイルにも出力しない)、
      そして PEAR のコアクラスをインクルードせずに済ませたいという場合は、
      このように設定します。
      <programlisting role="php">
       <![CDATA[
<?php
require_once 'HTML/CSS.php';

function myErrorHandler()
{
    return null;
}

$errorConf = array('error_handler' => 'myErrorHandler');
$css = new HTML_CSS(null, $errorConf);
// ...
?>
       ]]>
      </programlisting>
     </para>
    </tip>
   </para>

   <para>
    <note><title>HTML_CSS 1.4.0 以降のユーザ向けの注意</title>
     <para>
      エラーを画面に出力するかどうか、そしてログファイルに記録するかどうかを、
      HTML_CSS の関数コールで設定することもできます。
      <programlisting role="php">
       <![CDATA[
<?php
require_once 'HTML/CSS.php';

function myErrorAction($css_error)
{
    // $css_error は HTML_CSS_Error オブジェクトのインスタンスです。
    // これを画面に表示するなりログに記録するなりお好みの処理をします。
}

$errorConf = array('error_callback' => 'myErrorAction');
$css = new HTML_CSS(null, $errorConf);
// ...
?>
       ]]>
      </programlisting>
      あるいは、PEAR そのもののエラーハンドラ (PEAR::setErrorHandling,
      PEAR::pushErrorHandling, PEAR::popErrorHandling) を利用することもできます。
      <programlisting role="php">
       <![CDATA[
<?php
require_once 'HTML/CSS.php';

function myErrorAction($css_error)
{
    // $css_error は HTML_CSS_Error オブジェクトのインスタンスです。
    // これを画面に表示するなりログに記録するなりお好みの処理をします。
}

PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'myErrorAction');

$css = new HTML_CSS();
// ...
?>
       ]]>
      </programlisting>
     </para>
    </note>
   </para>

   <para>
    オプション <emphasis role="bold">push_callback</emphasis> を指定すると、
    スクリプトの実行を停止する (例外の場合はデフォルトでこうなります:
    定数 <constant>PEAR_ERROR_DIE</constant> を返します)
    かフィルタリングなしで続行する
    (<constant>NULL</constant> を返します)
    かどうかを決められます。
   </para>
   <para>
    独自のコールバック関数を <emphasis>push_callback</emphasis>
    に指定する場合、その関数は 2 つの引数をとるものでなければなりません。
    最初の引数はエラーコード、次の引数がエラーレベルとなります。
    フィルタリングに必要な情報はこれらだけです。
    以下の例は、スクリプトで引数の型を間違えた場合の処理を示すものです。
    <programlisting role="php">
     <![CDATA[
<?php
require_once 'HTML/CSS.php';

function myErrorFilter($code, $level)
{
    if ($code === HTML_CSS_ERROR_INVALID_INPUT) {
        error_log('script: '.__FILE__.' used wrong argument data type', 1, '[email protected]');
    }
    return null;
}

$errorConf = array('push_callback' => 'myErrorFilter');
$css = new HTML_CSS(null, $errorConf);
// ...
?>
     ]]>
    </programlisting>
   </para>
  </refsect1>

  <refsect1 id="package.html.html-css.errorhandler.context">
   <title>エラーコンテキストの表示</title>
   <simpara>
    場合によっては生成されるエラーの内容をカスタマイズしたくなるかもしれません。
    たとえば、個々のエラー (普通のエラー/例外) に対して発生時のファイル名や行番号、
    クラスや関数といった情報を含めると便利でしょう。
    たいていはデフォルトのオプションで十分でしょうが、
    コンテキスト情報の出力フォーマットを変更したくなるかもしれません。
   </simpara>

   <para>
    この例では、画面表示とログ出力の内容を変更します。
    <programlisting role="php">
     <![CDATA[
<?php
require_once 'HTML/CSS.php';

$displayConfig = array(
    'lineFormat' => '<b>%1$s</b>: %2$s<br />%3$s',
    'contextFormat' =>   '<b>ファイル名:</b> %1$s <br />'
                       . '<b>行番号:</b> %2$s <br />'
                       . '<b>関数名:</b> %3$s '
);
$logConfig = array(
    'lineFormat' => '%1$s %2$s [%3$s] %4$s',
    'timeFormat' => '%b'
);

$prefs = array(
    'handler' => array('display' => $displayConfig,
                       'log'     => $logConfig
));

$css = new HTML_CSS(null, $prefs);
// ...
$result = $css->setStyle('div', 'color', 5);
?>
     ]]>
    </programlisting>
   </para>

   <simpara>
    画面表示の内容は、次のようになります。
   </simpara>
   <informalexample>
     <screen>
Exception<co id="package.html.html-css.errorhandler.error.2.level"/>: invalid input, parameter #3 "$value" was expecting "string", instead got "integer"<co id="package.html.html-css.errorhandler.error.2.message"/>
ファイル名: [path_to]\[filename] <co id="package.html.html-css.errorhandler.error.2.context"/>
行番号: 22 <coref linkend="package.html.html-css.errorhandler.error.2.context"/>
関数名: html_css->setstyle <coref linkend="package.html.html-css.errorhandler.error.2.context"/>
     </screen>
     <calloutlist>
      <callout arearefs="package.html.html-css.errorhandler.error.2.level">
       <para>
        エラーレベル
       </para>
      </callout>
      <callout arearefs="package.html.html-css.errorhandler.error.2.message">
       <para>
        メッセージ本文とコンテキスト情報
       </para>
      </callout>
      <callout arearefs="package.html.html-css.errorhandler.error.2.context">
       <para>
        呼び出しコンテキスト (ファイル、行番号、関数)
       </para>
      </callout>
     </calloutlist>
   </informalexample>

   <simpara>
    ログの出力内容は、このようになります。
   </simpara>
   <informalexample>
     <screen>
Jun 127.0.0.1<co id="package.html.html-css.errorhandler.error.3.context"/> [exception<co id="package.html.html-css.errorhandler.error.3.level"/>] invalid input, parameter #3 "$value" was expecting "string", instead got "integer"<co id="package.html.html-css.errorhandler.error.3.message"/>
     </screen>
     <calloutlist>
      <callout arearefs="package.html.html-css.errorhandler.error.3.context">
       <para>
        クライアントの IP アドレスと実行日
       </para>
      </callout>
      <callout arearefs="package.html.html-css.errorhandler.error.3.level">
       <para>
        エラーレベル
       </para>
      </callout>
      <callout arearefs="package.html.html-css.errorhandler.error.3.message">
       <para>
        メッセージ本文とコンテキスト情報
       </para>
      </callout>
     </calloutlist>
   </informalexample>

   <note>
    <para>
     画面出力やログ出力をするには、それぞれ &php.ini; の
     <emphasis>display_errors</emphasis> と <emphasis>log_errors</emphasis>
     が &true; になっていなければなりません。
    </para>
   </note>

   <para>
    では、この結果をどのようにして得たのかを順を追ってみていきましょう。
   </para>
   <para>
    デフォルトのクラスには、ふたつのドライバ
    <emphasis>display</emphasis> と <emphasis>log</emphasis>
    があることを覚えておきましょう。これらにはそれぞれ独自の設定パラメータがあります。
    これらのパラメータの値を書き換えるには、HTML_CSS
    クラスのコンストラクタの 2 番目の引数で指定するハッシュの
    <emphasis role="bold">handler</emphasis> エントリを使用します。
   </para>
   <para>
    それを行っているのが、変数 <parameter>$prefs</parameter> です。
    この変数は 2 つのキーを持つ連想配列で、最初のキー <emphasis>display</emphasis>
    で表示用ドライバの値、2 番目のキー <emphasis>log</emphasis>
    でログ出力用のドライバの値を設定します。
   </para>

   <para>
    では、<emphasis>display</emphasis> ドライバの設定を見てみましょう。
    ここで再定義しているのは
    <simplelist type='inline'>
     <member>lineFormat</member>
     <member>contextFormat</member>
    </simplelist>
    の 2 つだけです。つまり、残りのキーである
    <simplelist type='inline'>
     <member>eol</member>
    </simplelist>
    についてはデフォルト値をそのまま使用するということです。以下の表を参照ください。
   </para>
   <para>
    <table><title>表示用ドライバの設定パラメータ</title>
     <tgroup cols="4">
      <thead>
       <row>
        <entry>パラメータ</entry>
        <entry>型</entry>
        <entry>デフォルト</entry>
        <entry>説明</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>eol</entry>
        <entry>string</entry>
        <entry>&lt;br /&gt;\n</entry>
        <entry>行末文字シーケンス</entry>
       </row>
       <row>
        <entry>lineFormat</entry>
        <entry>string</entry>
        <entry>&lt;b&gt;%1$s&lt;/b&gt;: %2$s %3$s</entry>
        <entry>ログに記録するフォーマットの指定:
         <itemizedlist>
          <listitem><simpara>1$ = エラーレベル</simpara></listitem>
          <listitem><simpara>2$ = エラーメッセージ (本文)</simpara></listitem>
          <listitem><simpara>3$ = エラーコンテキスト</simpara></listitem>
         </itemizedlist>
        </entry>
       </row>
       <row>
        <entry>contextFormat</entry>
        <entry>string</entry>
        <entry>
         in &lt;b&gt;%3$s&lt;/b&gt; (file &lt;b&gt;%1$s&lt;/b&gt; on line &lt;b&gt;%2$s&lt;/b&gt;)
        </entry>
        <entry>コンテキストのフォーマット (クラス、ファイル、行番号) の指定:
         <itemizedlist>
          <listitem><simpara>1$ = スクリプトのファイル名</simpara></listitem>
          <listitem><simpara>2$ = スクリプトファイルの行番号</simpara></listitem>
          <listitem><simpara>3$ = クラス/メソッド名</simpara></listitem>
         </itemizedlist>
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    <tip>
     <para>
      エラーメッセージにコンテキスト情報を表示させたくない場合は、
      <emphasis>lineFormat</emphasis> オプションのパラメータ %3$
      を削除しましょう。そうすれば、
      <emphasis>contextFormat</emphasis> が設定されていても表示されません。
     </para>
    </tip>
   </para>

   <para>
    では、次に <emphasis>log</emphasis> ドライバの独自設定を見てみましょう。
    ここで再定義しているのは
    <simplelist type='inline'>
     <member>lineFormat</member>
     <member>timeFormat</member>
    </simplelist>
    の 2 つだけなので、残りの 6 つのキー
    <simplelist type='inline'>
     <member>eol</member>
     <member>contextFormat</member>
     <member>ident</member>
     <member>message_type</member>
     <member>destination</member>
     <member>extra_headers</member>
    </simplelist>
    についてはデフォルト値をそのまま使用します。以下の表を参照ください。
   </para>
   <para>
    <table><title>ログ出力用ドライバの設定パラメータ</title>
     <tgroup cols="4">
      <thead>
       <row>
        <entry>パラメータ</entry>
        <entry>型</entry>
        <entry>デフォルト</entry>
        <entry>説明</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>eol</entry>
        <entry>string</entry>
        <entry>\n</entry>
        <entry>行末文字シーケンス</entry>
       </row>
       <row>
        <entry>lineFormat</entry>
        <entry>string</entry>
        <entry>%1$s %2$s [%3$s] %4$s %5$s </entry>
        <entry>ログに記録するフォーマットの指定:
         <itemizedlist>
          <listitem><simpara>$1 = エラー発生時刻</simpara></listitem>
          <listitem><simpara>2$ = ident (クライアントの IP アドレス)</simpara></listitem>
          <listitem><simpara>3$ = エラーレベル</simpara></listitem>
          <listitem><simpara>4$ = エラーメッセージ (本文)</simpara></listitem>
          <listitem><simpara>5$ = エラーコンテキスト</simpara></listitem>
         </itemizedlist>
        </entry>
       </row>
       <row>
        <entry>contextFormat</entry>
        <entry>string</entry>
        <entry>in %3$s (file %1$s on line %2$s) </entry>
        <entry>コンテキストのフォーマット (クラス、ファイル、行番号) の指定:
         <itemizedlist>
          <listitem><simpara>1$ = スクリプトのファイル名</simpara></listitem>
          <listitem><simpara>2$ = スクリプトファイルの行番号</simpara></listitem>
          <listitem><simpara>3$ = クラス/メソッド名</simpara></listitem>
         </itemizedlist>
        </entry>
       </row>
       <row>
        <entry>timeFormat</entry>
        <entry>string</entry>
        <entry>%b %d %H:%M:%S </entry>
        <entry>
         <ulink url="&url.php.lookup;strftime">strftime</ulink>
         が使用するタイムスタンプのフォーマット
        </entry>
       </row>
       <row>
        <entry>ident</entry>
        <entry>string</entry>
        <entry>REMOTE_ADDR </entry>
        <entry>クライアントの IP アドレス</entry>
       </row>
       <row>
        <entry>message_type</entry>
        <entry>string</entry>
        <entry>3 </entry>
        <entry>
         <ulink url="&url.php.lookup;error_log">error_log</ulink>
         が使用する出力先の形式
        </entry>
       </row>
       <row>
        <entry>destination</entry>
        <entry>string</entry>
        <entry>html_css_error.log </entry>
        <entry>
         <ulink url="&url.php.lookup;error_log">error_log</ulink>
         が使用する出力先の名前
        </entry>
       </row>
       <row>
        <entry>extra_headers</entry>
        <entry>string</entry>
        <entry>&null; </entry>
        <entry>出力先の形式に依存する追加ヘッダ</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    <tip>
     <para>
      エラーメッセージにコンテキスト情報を表示させたくない場合は、
      <emphasis>lineFormat</emphasis> オプションのパラメータ %5$
      を削除しましょう。そうすれば、
      <emphasis>contextFormat</emphasis> が設定されていても表示されません。
     </para>
    </tip>
   </para>
 </refsect1>

 <refsect1 id="package.html.html-css.errorhandler.messages">
  <title>独自のエラーメッセージの生成</title>
   <para>
    <classname>HTML_CSS_Error</classname> には、
    エラーメッセージを効率よく生成するためのメソッドが
    2 つ用意されています。
    これらを使用するには、以下のオプションを
    HTML_CSS クラスのコンストラクタ (2 番目の引数)
    で指定する必要があります。
   </para>

   <refsect2>
    <title>オプション: message_callback</title>
    <para>
     デフォルトのメッセージ処理コールバック
     (<methodname>HTML_CSS_Error::_getErrorMessage</methodname>)
     は、エラーコードとエラーメッセージテンプレートを対応させた
     次のような配列を受け取ります。
     <programlisting role="php">
      <![CDATA[
<?php
$messages = array(
    HTML_CSS_ERROR_UNKNOWN =>
        'unknown error',
    HTML_CSS_ERROR_INVALID_INPUT =>
        'invalid input, parameter #%paramnum% '
      . '"%var%" was expecting '
      . '"%expected%", instead got "%was%"'
);
?>
      ]]>
     </programlisting>
     基本的に、パーセント記号 (%) で囲まれている変数名は
     連想配列の値で置き換えられます。
    </para>
   </refsect2>

   <refsect2>
    <title>オプション: context_callback</title>
    <para>
     デフォルトのコンテキスト処理コールバック
     (<methodname>HTML_CSS_Error::getBackTrace</methodname>)
     は、実行した関数の配列を受け取ってエラーが発生した位置を見つけます。
    </para>
   </refsect2>
 </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
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../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
-->