PEAR 基底クラスは、ほとんどの PEAR クラスで使用される 標準的な機能を提供します。 通常、PEAR クラスのインスタンスを直接生成することはなく、 サブクラス化して使用します。
その主な機能を次に示します。
ClassName というクラス名で PEAR を継承した場合、 _ClassName (クラス名の前にアンダースコアを付けたもの)というメソッドを定義できます。 このメソッドは、リクエストが完了した時点でコールされます。 これは、オブジェクトを 「削除」 できるという意味ではデストラクタでは ありませんが、PHP が実行を完了した時点で、 PHP によりオブジェクトのコールバック関数としてコールされるという意味で デストラクタと呼ぶことができます。次の 例を参照してください。
重要!
デストラクタを正しく動作させるためには、クラスのインスタンス生成を 次のように "=& new" 演算子で行う必要があります。
<?php
$obj =& new MyClass();
?>"= new" を使用した場合、PEAR のシャットダウンリストに登録された オブジェクトは、コンストラクタがコールされた時点でのオブジェクトの コピーとなります。 この場合、このコピーの 「デストラクタ」 がシャットダウン要求時に コールされることになります。
PEAR 基底クラスは、true/false 値や数値コードといったものに比べ、 より複雑にエラーを渡す手段を提供します。 PEAR エラーはオブジェクトであり、 PEAR_Error クラス、または PEAR_Error を継承したクラスのインスタンスです。
PEAR エラーの設計指針に、ユーザには特定の形式の出力を強制するべきではなく、 場合によっては出力をまったく行わずにエラー処理を可能とするべき、 というものがあります。 これにより、出力形式が HTML 以外(たとえば WML や他の XML 形式)の場合にも、 高度なエラー処理が可能となります。
エラーオブジェクトは、生成時に様々な動作をさせるよう設定することができます。。 たとえば、エラーメッセージを出力する、メッセージを出力して終了する、 PHP の trigger_error() 関数でエラーを発生する、 コールバックを起動する、または、これら何もしない、などです。 これは、通常、PEAR_Error の コンストラクタで指定されます。ただし、すべてのパラメータは任意です。 また、PEAR クラス を基底とする各オブジェクトから生成されるエラーの デフォルト動作を設定することもできます。 エラーオブジェクトの使用法についてはPEAR エラーの例を、詳細については、 PEAR_Error リファレンスを参照してください。
次の例は、PEAR の「貧乏人のデストラクタもどき」の使用法を示します。 ファイルの中身を保持する簡単なクラスで、オブジェクトにデータを追加すると、 リクエスト終了時にファイルにデータを書き戻すというコードです。
PEAR 擬似デストラクタ
<?php
require_once "PEAR.php";
class FileContainer extends PEAR
{
var $file = '';
var $contents = '';
var $modified = 0;
function FileContainer($file)
{
$this->PEAR(); // 親クラスのコンストラクタをコール
$fp = fopen($file, "r");
if (!is_resource($fp)) {
return;
}
while ($data = fread($fp, 2048)) {
$this->contents .= $data;
}
fclose($fp);
}
function append($str)
{
$this->contents .= $str;
$this->modified++;
}
// 「デストラクタ」 はコンストラクタと似た名前でが、
// 前にアンダースコアが付いています。
function _FileContainer()
{
if ($this->modified) {
$fp = fopen($this->file, "w");
if (!is_resource($fp)) {
return;
}
fwrite($fp, $this->contents);
fclose($fp);
}
}
}
$fileobj =& new FileContainer("testfile");
$fileobj->append("this ends up at the end of the file\n");
// リクエストが完了し、PHP がシャットダウンする時、$fileobj の
// 「デストラクタ」 がコールされ、ディスク上のファイルが更新されます。
?>
PEAR 「デストラクタ」 は、PHP のシャットダウン時のコールバック (register_shutdown_function()) を使用します。 そのため、PHP < 4.1 では、PHP が Web サーバで実行されている場合は デストラクタからは何も出力できません。 PHP がコマンドラインモードで使用されている場合を除き、 デストラクタからの出力はすべて失われます。 PHP 4.1 以降では、デストラクタにおいても出力を行うことが可能です。 また、デストラクタを使用する場合は、オブジェクトのインスタンス生成に関する 警告 も参照してください。
次の例は、PEAR のエラー処理機構の別の使用方法を説明するものです。
PEAR エラーの例 (1)
<?php
function mysockopen($host = "localhost", $port = 8090)
{
$fp = fsockopen($host, $port, $errno, $errstr);
if (!is_resource($fp)) {
return new PEAR_Error($errstr, $errno);
}
return $fp;
}
$sock = mysockopen();
if (PEAR::isError($sock)) {
print "mysockopen error: ".$sock->getMessage()."<BR>\n"
}
?>
この例は、fsockopen() 関数のラッパです。 fsockopen が返すエラーコードおよびメッセージを PEAR エラーオブジェクトで返します。 返された値が PEAR エラーかどうか調べるには PEAR::isError() を使用するということに注目してください。
この例での PEAR_Error の実行モードは、エラーオブジェクトを返し、 ユーザ(プログラマ)にその後の処理を託す、というものです。 これは、デフォルトのエラーモードです。
次の例では、エラーモードのデフォルトを設定する方法を示します。
PEAR エラーの例 (2)
<?php
class TCP_Socket extends PEAR
{
var $sock;
function TCP_Socket()
{
$this->PEAR();
}
function connect($host, $port)
{
$sock = fsockopen($host, $port, $errno, $errstr);
if (!is_resource($sock)) {
return $this->raiseError($errstr, $errno);
}
}
}
$sock = new TCP_Socket;
$sock->setErrorHandling(PEAR_ERROR_DIE);
$sock->connect("localhost", 8090);
print "still alive<BR>\n";
?>
この例では、エラーモードのデフォルトを PEAR_ERROR_DIE に設定しています。 raiseError のコールにあたって、 (3番目のパラメータに)エラーモードを設定していないため、 raiseError はデフォルトのエラーモードを使用し、 fsockopen が失敗するとスクリプトの実行を終了します。
PEAR クラスは、グローバルなデフォルトと
「デストラクタ」で使用されるオブジェクトのリストを登録するために
いくつかのグローバル変数を使用します。
PEAR クラスに関連するすべてのグローバル変数は、
接頭辞 _PEAR_
を有します。
この変数は、直接設定せずに、次のようにスタティックメソッド PEAR::setErrorHandling() をコールして下さい。
<?php
PEAR::setErrorHandling(PEAR_ERROR_DIE);
?>
この変数は、直接設定せずに、次のようにスタティックメソッド PEAR::setErrorHandling() をコールして下さい。
<?php
PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_ERROR);
?>
この場合も、この変数を直接設定せずに、次のようにスタティックメソッド PEAR::setErrorHandling() をコールして下さい。
<?php
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_error_handler");
?>
コールバック関数を再度指定せずに切替える方法の例を示します。
<?php
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_function_handler");
do_some_stuff();
PEAR::setErrorHandling(PEAR_ERROR_DIE);
do_some_critical_stuff();
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK);
// ここで my_function_handler を使用する状態に戻ります
?>