エラーハンドラ

導入

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

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

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

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

$css = new HTML_CSS();

$result = $css->setStyle('div', 'color', 5);
if (PEAR::isError($result)) {
    // 何らかのエラー処理
}
?>

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

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

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

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

ハンドラの設定

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

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

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

エラーの発生の制御

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

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

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

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

<?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, 'admin@yoursite.com');
    }
    return null;
}

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

エラーコンテキストの表示

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

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

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

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

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"

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

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

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

では、display ドライバの設定を見てみましょう。 ここで再定義しているのは lineFormat, contextFormat の 2 つだけです。つまり、残りのキーである eol についてはデフォルト値をそのまま使用するということです。以下の表を参照ください。

独自のエラーメッセージの生成

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

<?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%"'
);
?>