HTML_CSS パッケージには、柔軟なエラーハンドラプラグインシステムが組み込まれており、 お好みのエラーハンドラを使用することができます。 PEAR_Error オブジェクト (デフォルト) 以外にも PEAR_ErrorStack パッケージや その他のエラーハンドラをプラグインすることができます。

何も設定をしなければ、HTML_CSS の API で発生したエラー (普通のエラーや例外) は HTML_CSS_Error オブジェクトを生成して呼び出し元 (ユーザスクリプト) に返します。

他の PEAR パッケージが出した PEAR_Error と HTML_CSS のエラーを区別する簡単な方法は HTML_CSS::isError() です。 また、エラーのレベル (警告、エラー、例外) を取得するには HTML_CSS_Error::getLevel() メソッドを使用します。

使い慣れた PEAR のエラー処理用 API も使えます。

出力結果は、このようになるでしょう。

Exception*: invalid input, parameter #3 "$value" was expecting "string",
instead got "integer"** in html_css->setstyle (file [path_to]\[filename] on line 6)***
     

この標準の挙動では不満があるかもしれませんが、心配無用です。 すべてを変更することができます。

• エラーを表示するか無視するか

• メッセージの一部 (エラーレベル、本文、コンテキスト) の表示/非表示

HTML_CSS は、 display_errors および log_errors のプロトコルに従っています。

エラーハンドラを設定するには、コンストラクタの引数を使用します。 パラメータの概要を、以下に示します。

より綿密なエラー処理が必要となる場面も多々あります。

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

すべてのエラーを無視したい (画面にもログファイルにも出力しない)、 そして PEAR のコアクラスをインクルードせずに済ませたいという場合は、 このように設定します。

<?php
require_once 'HTML/CSS.php';

function myErrorHandler()
{
    return null;
}

$errorConf = array('error_handler' => 'myErrorHandler');
$css = new HTML_CSS(null, $errorConf);
// ...
?>

HTML_CSS 1.4.0 以降のユーザ向けの注意

エラーを画面に出力するかどうか、そしてログファイルに記録するかどうかを、 HTML_CSS の関数コールで設定することもできます。

<?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);
// ...
?>

あるいは、PEAR そのもののエラーハンドラ (PEAR::setErrorHandling, PEAR::pushErrorHandling, PEAR::popErrorHandling) を利用することもできます。

<?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();
// ...
?>

オプション push_callback を指定すると、 スクリプトの実行を停止する (例外の場合はデフォルトでこうなります: 定数 PEAR_ERROR_DIE を返します) かフィルタリングなしで続行する (NULL を返します) かどうかを決められます。

独自のコールバック関数を push_callback に指定する場合、その関数は 2 つの引数をとるものでなければなりません。 最初の引数はエラーコード、次の引数がエラーレベルとなります。 フィルタリングに必要な情報はこれらだけです。 以下の例は、スクリプトで引数の型を間違えた場合の処理を示すものです。

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

この例では、画面表示とログ出力の内容を変更します。

画面表示の内容は、次のようになります。

Exception****: invalid input, parameter #3 "$value" was expecting "string", instead got "integer"*****
ファイル名: [path_to]\[filename] ******
行番号: 22 
関数名: html_css->setstyle 
     

ログの出力内容は、このようになります。

Jun 127.0.0.1******* [exception********] invalid input, parameter #3 "$value" was expecting "string", instead got "integer"*********
     

画面出力やログ出力をするには、それぞれ php.ini の display_errors と log_errors が TRUE になっていなければなりません。

では、この結果をどのようにして得たのかを順を追ってみていきましょう。

デフォルトのクラスには、ふたつのドライバ display と log があることを覚えておきましょう。これらにはそれぞれ独自の設定パラメータがあります。 これらのパラメータの値を書き換えるには、HTML_CSS クラスのコンストラクタの 2 番目の引数で指定するハッシュの handler エントリを使用します。

それを行っているのが、変数 $prefs です。 この変数は 2 つのキーを持つ連想配列で、最初のキー display で表示用ドライバの値、2 番目のキー log でログ出力用のドライバの値を設定します。

では、display ドライバの設定を見てみましょう。 ここで再定義しているのは

• lineFormat
• contextFormat

• eol

エラーメッセージにコンテキスト情報を表示させたくない場合は、 lineFormat オプションのパラメータ %3$ を削除しましょう。そうすれば、 contextFormat が設定されていても表示されません。

では、次に log ドライバの独自設定を見てみましょう。 ここで再定義しているのは

• lineFormat
• timeFormat

• eol
• contextFormat
• ident
• message_type
• destination
• extra_headers

エラーメッセージにコンテキスト情報を表示させたくない場合は、 lineFormat オプションのパラメータ %5$ を削除しましょう。そうすれば、 contextFormat が設定されていても表示されません。

HTML_CSS_Error には、 エラーメッセージを効率よく生成するためのメソッドが 2 つ用意されています。 これらを使用するには、以下のオプションを HTML_CSS クラスのコンストラクタ (2 番目の引数) で指定する必要があります。