はじめに

説明

PEAR 基底クラスは、ほとんどの PEAR クラスで使用される 標準的な機能を提供します。 通常、PEAR クラスのインスタンスを直接生成することはなく、 サブクラス化して使用します。

その主な機能を次に示します。

• シャットダウンリクエストによるオブジェクト 「デストラクタ」

• エラー処理

PEAR デストラクタ

ClassName というクラス名で PEAR を継承した場合、 _ClassName （クラス名の前にアンダースコアを付けたもの）というメソッドを定義できます。 このメソッドは、リクエストが完了した時点でコールされます。 これは、オブジェクトを 「削除」 できるという意味ではデストラクタでは ありませんが、PHP が実行を完了した時点で、 PHP によりオブジェクトのコールバック関数としてコールされるという意味で デストラクタと呼ぶことができます。次の 例を参照してください。

<?php
$obj =& new MyClass();
?>

PEAR エラー処理

PEAR 基底クラスは、true/false 値や数値コードといったものに比べ、 より複雑にエラーを渡す手段を提供します。 PEAR エラーはオブジェクトであり、 PEAR_Error クラス、または PEAR_Error を継承したクラスのインスタンスです。

PEAR エラーの設計指針に、ユーザには特定の形式の出力を強制するべきではなく、 場合によっては出力をまったく行わずにエラー処理を可能とするべき、 というものがあります。 これにより、出力形式が HTML 以外（たとえば WML や他の XML 形式）の場合にも、 高度なエラー処理が可能となります。

エラーオブジェクトは、生成時に様々な動作をさせるよう設定することができます。。 たとえば、エラーメッセージを出力する、メッセージを出力して終了する、 PHP の trigger_error() 関数でエラーを発生する、 コールバックを起動する、または、これら何もしない、などです。 これは、通常、PEAR_Error の コンストラクタで指定されます。ただし、すべてのパラメータは任意です。 また、PEAR クラス を基底とする各オブジェクトから生成されるエラーの デフォルト動作を設定することもできます。 エラーオブジェクトの使用法についてはPEAR エラーの例を、詳細については、 PEAR_Error リファレンスを参照してください。

例

次の例は、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
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 の実行モードは、エラーオブジェクトを返し、 ユーザ（プログラマ）にその後の処理を託す、というものです。 これは、デフォルトのエラーモードです。

次の例では、エラーモードのデフォルトを設定する方法を示します。

<?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_ を有します。