Zend とは何 ? そして PHP とは何 ?

Zend という名前は PHP のコアとなる言語エンジンを 指します。PHP は、外部から見た際のシステム全体を 指す単語です。最初はすこし紛らわしく感じるかもしれませんが、これは そんなに複雑な話ではありません (以下を参照ください)。 Web スクリプトのインタプリタを実装するには、3 つのパートが必要です。

1. インタプリタ (interpreter) は 入力コードを解析し、変換し、そして実行します。

2. 機能 (functionality) は、言語の機能 (関数など) を実装します。

3. インターフェイス (interface) は、 Web サーバなどと会話をします。

1 のすべてと 2 の一部を担当するのが Zend で、2 および 3 を 担当するのが PHP です。この 2 つをあわせることで PHP パッケージが 完成します。Zend 自身は言語のコアのみを受け持つもので、 事前に定義された関数などの PHP の基本部分のみを実装します。 PHP が、この言語の優れた可能性を作り出しているすべての 拡張モジュールを受け持ちます。

これ以降のセクションでは、PHP を拡張するにはどこをどのように変更すれば よいのかを説明します。

外部モジュール

外部モジュールは、スクリプトの実行時に dl() 関数を使用して読み込みます。この関数は、ディスクから共有オブジェクトを 読み込んで、呼び出し元のスクリプトからその機能を使用できるように します。スクリプトが終了すると、外部モジュールはメモリから削除 されます。この方法には利点も欠点もあります。それを以下の表にまとめます。

要するに、外部モジュールが有用なのは以下のような場合です。 サードパーティの製品・PHP のちょっとした機能拡張で、めったに 使われないもの・単なるテスト目的で作成するものなど。 追加機能を手っ取り早く開発するには、外部モジュールが最適です。 頻繁に使用するものであったり大規模な実装であったり、あるいは 複雑なコードの場合などは、欠点が利点を上回ってしまうでしょう。

サードパーティは、php.ini の extension タグを使用して PHP に拡張モジュールを 追加することを考えるかもしれません。これらの拡張モジュールは 本体のパッケージとは完全に切り離されます (これは、商用の環境では とても便利な機能です)。商用製品を配布する場合は、単に追加モジュール のみを含むディスクやアーカイブを出荷すればよいのであり、他の 拡張モジュールが使用できなくなるような PHP バイナリを作成する 必要がなくなります。

組み込みモジュール

組み込みモジュールは、PHP のコンパイル時に直接組み込まれ、PHP プロセスと一緒に動作します。すべてのスクリプトで、その機能が 使用可能となります。外部モジュールの場合と同様、組み込みモジュールに ついても利点と欠点があります。それを以下の表にまとめます。

比較的変更の少ない安定した関数のライブラリで、平均以上の速度を 要求するものであったり、あるいは多くのスクリプトから頻繁に 使用されるようなライブラリなどの場合は、組み込みモジュールに するのが最適です。PHP を再コンパイルしなければならないという 問題は、それによって得られるスピードや使いやすさにくらべたら たいしたことはありません。しかし、小さな変更が頻繁に繰り返される ような場合には、組み込みモジュールは不適当です。

Zend エンジン

もちろん、拡張機能を Zend エンジンに直接組み込むこともできます。 言語そのものの振る舞いを変更したい場合、あるいは言語のコアに 特別な関数を直接組み込む必要がある場合などには、この方式がよいでしょう。 しかし、一般的には Zend エンジンを変更することは避けるべきです。 ここを変更してしまうとその他の部分で非互換性が発生する可能性があり、 特別に変更された Zend エンジンに対応できる人は誰もいなくなるでしょう。 変更内容を PHP のソースから切り離すことができなくなりますし、 また「公式」なソースリポジトリからアップデートを行うと、変更内容が 上書きされてしまいます。そのため、この手法はよくないものと 考えられています。使用することはめったにないため、この文書では この手法については取り上げません。

拡張規約

Zend は、ある規約に基づいて構築されています。 この標準規約を破ることを避けるため、 以下の節で説明する規則を守らなければなりません。

マクロ

重要なタスクのほぼ全てについて、Zend では便利なマクロを定義しています。 以下の表および図で、基本的な関数・構造体およびマクロについて 説明しています。マクロ定義のほとんどは zend.h あるいは zend_API.h にあります。この章を勉強したあとで、 これらのファイルをじっくり読んでみることをお勧めします (もちろん今この場で読んでもよいのですが、 まだこの段階ではすべてを理解することはできないでしょう)。

メモリ管理

特にサーバソフトウェアにとって、リソース管理は重大な問題です。 メモリは最も貴重なリソースのひとつなので、 メモリ管理には最大限の注意を払わねばなりません。 メモリ管理の一部は Zend によって抽象化されており、 この抽象化を使用すべきなのは明白です。この抽象化を使用することにより、 Zend はすべてのメモリ割り当てを完全に制御できるようになります。 そのブロックが使用中なのかどうかを Zend が判断し、 未使用のブロックや参照されていないブロックを自動的に開放することで メモリリークを防ぐことができます。 このために使用する関数を、以下の表にまとめます。

emalloc() および estrdup()、estrndup()、 ecalloc()、erealloc() は、内部メモリを確保します。efree() は、これらの関数で確保したブロックを開放します。 e*() 関数が管理するメモリは、 現在のプロセス内でローカルであるものとして扱われます。 このプロセスによって実行されているスクリプトが終了すると、 すぐにメモリが破棄されます。

ディレクトリ関数およびファイル関数

Zend モジュール内では、以下のディレクトリ関数およびファイル関数を使用しなければなりません。 これらの関数の機能はそれぞれ対応する C 関数と同じですが、 さらにスレッドレベルでの仮想実行ディレクトリがサポートされています。

文字列の処理

Zend エンジンでは、文字列はその他の値 (整数値、論理値など) と少し異なる方法で処理されます。 これらの値を保存するために、追加のメモリを確保する必要はありません。 関数から文字列を返したい場合は、新しい文字列変数を シンボルテーブルかそれに類似のものに登録します。 その文字列が使用するメモリは、先ほど説明した e*() 関数で事前に確保しておかなければなりません (この段階では、まだあまりピンとこないかもしれません。 とりあえずは頭の片隅に置いておいてください。あとでもう一度説明します)。

複雑な型

配列やオブジェクトのような複雑な型については、扱いかたが異なります。 Zend はこれらの型を扱うための API を提供しており、 これらの型はハッシュテーブルとして保存されます。

注意: これ以降のサンプルソースでは、 読みやすさを考慮して integer などの単純な型のみを使用します。 より高度な型を作成する方法については、この章の後半で説明します。

モジュールのコンパイル

モジュールをコンパイルするには、基本的に 2 種類の方法があります。

• ext ディレクトリ内で、 提供されている "make" 機構を使用します。 これは、動的ロードモジュールを作成することも可能です。

• ソースを手動でコンパイルします。

最初の方法のほうが断然お勧めです。PHP 4.0 以降、 この仕組みは標準化され、洗練されたビルド手順に組み込まれています。 あまりに洗練されすぎているという事実は、裏を返せば欠点でもあります。 つまり、最初のうちはなかなか理解できないということです。 この章の後半ではより詳細に説明しますが、 まず最初はデフォルトのファイルを使用して進めていきましょう。

2 番目の方法は、(何らかの理由で) PHP の完全なソースツリーを もっていない、すべてのファイルに対するアクセス権限がない、 あるいは単にキーボードと戯れていたいなどといった人たちにお勧めです。 これらはどれもめったにないケースではありますが、 この文書を完全なものにするためにこちらの方法についても説明しておきます。

Make を使用したコンパイル

サンプルソースを標準的な仕組みでコンパイルするには、 PHP ソースツリーの ext ディレクトリ以下に サンプルのディレクトリをコピーします。 それから buildconf を実行すると、 新しい拡張モジュール用の適切なオプションを含む configure スクリプトが作成されます。 デフォルトでは、すべてのサンプルソースは無効になります。 そのため、この作業でビルド手順が破壊されてしまう恐れはありません。

buildconf を実行すると、configure --help の結果に以下が追加されます。

  --enable-array_experiments   BOOK: Enables array experiments
  --enable-call_userland       BOOK: Enables userland module
  --enable-cross_conversion    BOOK: Enables cross-conversion module
  --enable-first_module        BOOK: Enables first module
  --enable-infoprint           BOOK: Enables infoprint module
  --enable-reference_test      BOOK: Enables reference test module
  --enable-resource_test       BOOK: Enables resource test module
  --enable-variable_creation   BOOK: Enables variable-creation module

先ほど Zend API: PHP のコアをハックする で示したモジュールは、 --enable-first_module あるいは --enable-first_module=yes で使用可能になります。

手動でのコンパイル

モジュールを手動でコンパイルするには、以下のコマンドを実行しなければなりません。

モジュールをコンパイルするためのコマンドでは、コンパイラに対して 位置独立なコードを出力するように指示しています (-fpic は省略できません)。 また、定数 COMPILE_DL_FIRST_MODULE を指定することで、 モジュールのコードを動的ロード可能なモジュールとしてコンパイルするようにしています (上のテストモジュールではこれをチェックしています。これについては後で説明します)。 これらのオプションに続いて、ソースファイルをコンパイルするために必要な 最小限の標準インクルードパスを指定しています。

注意: サンプルのインクルードパスは、すべて ext ディレクトリからの相対パスです。 別の場所でコンパイルする場合は、それに応じてパスを変更してください。 必要なのは、PHP ディレクトリおよび Zend ディレクトリ、そして (必要に応じて) モジュールの存在するディレクトリです。

リンク用のコマンドも、動的モジュールとしてリンクするためのごく平凡なものです。

コンパイル用のコマンドに最適化オプションを含めることもできますが、 この例では省略しています (しかし、いくつかのオプションは 先に説明した makefile のテンプレートに含められています)。

注意: 手動でのコンパイルおよびリンクで PHP に静的モジュールとして組み込む手順は、非常に面倒なものとなります。 そのため、ここでは扱いません (これらのコマンドをすべてタイプするのは効率的ではありません)。

モジュールの構造

すべての PHP モジュールは、共通の構造に従っています。

• ヘッダファイルのインクルード (必要なすべてのマクロ、API、define などをインクルードするため)

• エクスポートする関数の C での宣言 (Zend 関数ブロックの宣言のために必要)

• Zend 関数ブロックの宣言

• Zend モジュールブロックの宣言

• get_module() の実装

• エクスポートするすべての関数の実装

ヘッダファイルのインクルード

モジュールに組み込まなければならない唯一のヘッダファイルは php.h で、これは PHP ディレクトリにあります。 このファイルは、新しいモジュールを使用できるようにビルドするための すべてのマクロ定義、API 定義を含みます。

豆知識: モジュール固有の定義を含むヘッダファイルを、 別に分けて作成しておくとよいでしょう。 エクスポートされるすべての関数の定義をこのヘッダファイルに含め、 そしてこのファイルで php.h をインクルードします。 ext_skel を使用して雛形を作成したのなら、 すでにこの形式のヘッダファイルが出来上がっているはずです。

エクスポートする関数の宣言

エクスポートする (つまり PHP の新しいネイティブ関数として使用できるようにする) 関数を宣言するためには、Zend が提供するマクロを使用します。 宣言は、このように行います。

ZEND_FUNCTION ( my_function );

ZEND_FUNCTION は、Zend の内部 API を満たす新しい C 関数を宣言します。内部 API を満たすとは、 その関数の型が void であり、パラメータとして INTERNAL_FUNCTION_PARAMETERS (別のマクロ) を受け取るということです。さらに、関数名の先頭に zif を付加します。これらの定義を満たす宣言の例は、次のようになります。

void zif_my_function ( INTERNAL_FUNCTION_PARAMETERS );

INTERNAL_FUNCTION_PARAMETERS を展開した結果は、次のようになります。

void zif_my_function( int ht
                    , zval * return_value
                    , zval * this_ptr
                    , int return_value_used
                    , zend_executor_globals * executor_globals
                    );

インタプリタおよびエグゼキュータのコアは PHP 本体のパッケージとは分離されているので、 マクロや関数群を定義するもうひとつの API が作られました。これが Zend API です。今のところ Zend API は、 かつて PHP が担当していた機能のうちのごくわずかしか処理できません。 PHP の関数の多くは Zend のマクロに書き下ろされており、 その内部で Zend API をコールしています。 おすすめのやりかたは、まずできる限り Zend API を使用することです。 というのは古い API は互換性のためだけに残されているものだからです。 例えば、zval 型と pval 型はまったく同じものです。 zval は Zend での定義で、pval は PHP での定義です (実際のところ、現在 pval は zval のエイリアスとなっています)。 INTERNAL_FUNCTION_PARAMETERS は Zend のマクロなので、 上の宣言には zval が用いられています。 コードを書く際には、新しい Zend API のために常に zval を使うようにしましょう。

この宣言のパラメータリストは非常に重要です。これらは常に頭に入れておくようにしましょう。 (Zend API: PHP のコアをハックする を参照ください)。

Zend 関数ブロックの宣言

エクスポートする関数の宣言が完了しました。こんどはさらにそれを Zend に登録しなければなりません。関数のリストを登録するには、 zend_function_entry の配列を使用します。 この配列には、外部に公開するすべての関数について PHP で使用する場合の名前と C ソース内で定義されている名前が含まれています。 内部的には、zend_function_entry は Zend API: PHP のコアをハックする のように定義されています。

typedef struct _zend_function_entry {
    char *fname;
    void (*handler)(INTERNAL_FUNCTION_PARAMETERS);
    unsigned char *func_arg_types;
} zend_function_entry;

上の例では、このような宣言になります。

zend_function_entry firstmod_functions[] =
{
    ZEND_FE(first_module, NULL)
    {NULL, NULL, NULL}
};

リストの最後のエントリは、必ず {NULL, NULL, NULL} でなければなりません。 エクスポートされる関数の一覧が終わることを Zend が知るために、 このエントリが必要となります。

注意: 最後を表す印として、定義済みマクロを使用することは できません。そうすると、 "NULL" という名前の関数を探しにいってしまいます!

マクロ ZEND_FE ('Zend Function Entry' を省略したものです) は、構造体のエントリを単純に zend_function_entry に展開します。 これらのマクロは特別な命名規約を持っていることに注意しましょう。 あなたが作成する C 関数の名前には、前に zif_ をつけることになります。つまり、ZEND_FE(first_module) は zif_first_module() という名前の C 関数を参照するということです。このマクロと手書きのエントリを混ぜて使用する場合には (お勧めしません) これを頭に入れておきましょう。

豆知識: zif_*() という名前の関数でコンパイルエラーが出た場合は、 ZEND_FE で定義した関数がかかわっています。

Zend API: PHP のコアをハックする が、 関数の定義に使用できるすべてのマクロの一覧です。

注意: ZEND_FE と PHP_FUNCTION を組み合わせて使用したり、あるいは PHP_FE と ZEND_FUNCTION を組み合わせて使用したりすることはできません。しかし、 各関数について ZEND_FE と ZEND_FUNCTION、あるいは PHP_FE と PHP_FUNCTION という組み合わせが守られているのなら、 それらを混用することは可能です。 しかし、混用することは 推奨しません。 ZEND_* マクロだけを使用するようにしましょう。

Zend モジュールブロックの宣言

このブロックは構造体 zend_module_entry に保存され、モジュールの内容について Zend に示すために必要な すべての情報が含まれます。このモジュールの内部定義は Zend API: PHP のコアをハックする で確認できます。

typedef struct _zend_module_entry zend_module_entry;
     
    struct _zend_module_entry {
    unsigned short size;
    unsigned int zend_api;
    unsigned char zend_debug;
    unsigned char zts;
    char *name;
    zend_function_entry *functions;
    int (*module_startup_func)(INIT_FUNC_ARGS);
    int (*module_shutdown_func)(SHUTDOWN_FUNC_ARGS);
    int (*request_startup_func)(INIT_FUNC_ARGS);
    int (*request_shutdown_func)(SHUTDOWN_FUNC_ARGS);
    void (*info_func)(ZEND_MODULE_INFO_FUNC_ARGS);
    char *version;

[ 構造体の残りの部分は、ここではあまり関係がありません ]

};

今回の例では、この構造体を次のように実装します。

zend_module_entry firstmod_module_entry =
{
    STANDARD_MODULE_HEADER,
    "First Module",
    firstmod_functions,
    NULL, NULL, NULL, NULL, NULL,
    NO_VERSION_YET,
    STANDARD_MODULE_PROPERTIES,
};

これは、基本的に必要最小限の設定です。モジュール名は First Module とし、関数一覧の参照を設定し、 スタートアップ関数やシャットダウン関数はすべて未使用としています。

参照用として、スタートアップ関数およびシャットダウン関数に関するマクロを Zend API: PHP のコアをハックする にまとめておきます。 これらは今回の例では使用しませんが、後で説明します。 スタートアップ関数やシャットダウン関数を宣言する際にはこれらのマクロを使用すべきです。 というのもこれらの関数には特別なパラメータ (INIT_FUNC_ARGS および SHUTDOWN_FUNC_ARGS) を渡さなければならず、 定義済みマクロを使用することでこれらが自動的に関数宣言に組み込まれるからです。 仮にこれらの関数を (マクロを使用せずに) 手動で宣言したとしましょう。 もし PHP の開発者が何らかの事情で引数を変更したとすると、 それに追従するためにあなたは自分のモジュールのソースを変更しなければならなくなります。

get_module() の作成

これは特別な関数で、すべての動的読み込みモジュールで使用されます。 これを作成するため、まずは ZEND_GET_MODULE を見てみましょう。

#if COMPILE_DL_FIRSTMOD
     ZEND_GET_MODULE(firstmod) 
#endif

関数の実装が、条件付きコンパイル文で囲まれています。なぜかというと、 get_module() 関数が必要となるのは あなたのモジュールが動的モジュールとしてビルドされる場合だけだからです。 コンパイラのコマンドで COMPILE_DL_FIRSTMOD を定義することにより (動的モジュールとしてビルドするための コンパイル手順については上記を参照ください)、 動的モジュールとしてビルドするのか組み込みモジュールとしてビルドするのかを 指示することができます。組み込みモジュールを作成する場合は、 get_module() の実装は単純に取り除かれます。

get_module() は、 Zend がモジュールを読み込む際にコールされます。 例えば、スクリプト内で dl() がコールされた場合などです。この関数の目的は、モジュール情報ブロックを Zend に返し、モジュールの内容をエンジンに教えることです。

動的モジュールで get_module() 関数を実装しなかった場合、 Zend がそのモジュールにアクセスしようとした際にエラーとなります。

エクスポートするすべての関数の実装

あとは、エクスポートする関数を実装すれば終わりです。 first_module では、例としてこのような関数を使用します。

ZEND_FUNCTION(first_module)
{
    long parameter;

    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &parameter) == FAILURE) {
        return;
    }

    RETURN_LONG(parameter);
}

関数の宣言には ZEND_FUNCTION を使用します。 これは、関数エントリテーブルにおける ZEND_FE に対応しています (こちらについては先ほど説明しました)。

関数宣言の後には、引数のチェックおよびその内容の取得、 引数の変換、そして返り値の作成などのコードが続きます (これらの詳細は後述します)。

まとめ

基本的に、これですべてです。PHP モジュールを構成するのに、 これ以上のものは必要ありません。組み込みのモジュールについても その構造は動的モジュールと同じです。 ここまでに説明した内容を身に着けておけば、今後 PHP モジュールのソースファイルを読んでいく際につまづくこともなくなるでしょう。

さあ、これ以降の節で PHP の内部構造について学び、 強力な拡張モジュールを作っていきましょう。

引数の数の定義

PHP が正式な関数宣言を行わないためにコール時の文法チェックが行われない、 また PHP が可変引数をサポートしているなどの理由で、 実際にその関数にいくつの引数が渡されたのかを知らなければならないこともあるでしょう。 そのような場合には ZEND_NUM_ARGS マクロを使用します。 以前のバージョンの PHP では、コール時の引数の数を取得するために このマクロは関数のハッシュテーブルのエントリ ht を使用していました。このエントリは INTERNAL_FUNCTION_PARAMETERS のリストから渡されました。 関数に渡された引数の数は今では ht 自体に含まれているので、ZEND_NUM_ARGS はダミーのマクロとなっています (実際の定義は zend_API.h を参照ください)。 しかし、今後のことを考えると、 呼び出しインターフェイスが変わっても互換性を保ち続けられるように このマクロを使用しておくことをお勧めします。 注意: 昔の PHP では、このマクロと同等の働きをするのは ARG_COUNT マクロでした。

引数の数が正しいかどうかを調べるコードは次のようになります。

関数コール時の引数の数が 2 つでなかった場合、 これはエラーメッセージを表示して終了します。 上のコードは、WRONG_PARAM_COUNT マクロの使用例でもあります。 これは、以下のような標準的なエラーメッセージを生成するために使用するものです。

"Warning: Wrong parameter count for firstmodule() in /home/www/htdocs/firstmod.php on line 5"

このマクロはデフォルトのエラーメッセージを表示し、呼び出し元に制御を戻します。 このマクロの定義もまた zend_API.h にあります。このような内容です。

ZEND_API void wrong_param_count(void);

#define WRONG_PARAM_COUNT { wrong_param_count(); return; }

ご覧の通り、このマクロは wrong_param_count() という名前の内部関数をコールしています。 この関数が警告を表示しています。独自のエラーメッセージを作成するための方法については、 後半の節「情報の表示」を参照ください。

引数の取得

注意: パラメータのパース用の新しい API
この章では、Andrei Zmievski による新しい Zend パラメータパース用 API を説明します。この API は PHP 4.0.6 から PHP 4.1.0 の間の開発中に導入されました。

パラメータのパースはあまりにもありふれた操作であり、少し退屈に感じることもあるでしょう。 また、エラーチェックやエラーメッセージは標準化されていたほうがいいでしょう。 PHP 4.1.0 以降では、パラメータのパース用の新しい API を使用することでこれが実現できます。 この API はパラメータの受け取りを劇的に単純化していますが、 可変引数を受け取る関数には使用できないという弱点があります。 しかし、大半の関数では、引数の数は固定です。そのため、 新しい標準として、このパース用 API の使用を推奨します。

パラメータのパース用関数のプロトタイプは、このようになります。

int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);

最初の引数に、あなたの関数が受け取るパラメータの数を指定します。 ここでは ZEND_NUM_ARGS() が使用できます。 2 番目のパラメータは、常に TSRMLS_CC マクロでなければなりません。3 番目の引数は、 あなたの関数が受け取る引数の数および型を表す文字列です。 これは、printf の書式指定文字列によって出力内容を指定するのに似ています。 そして最後に、パラメータの値を受け取る変数へのポインタを指定します。

常に希望通りの型でデータを受け取ることができるよう、 zend_parse_parameters() は可能な範囲で型変換を行います。 あらゆるスカラー型は別のスカラー方に変換することが可能です。 しかし、複雑な型 (配列、オブジェクトあるいはリソース) とスカラー型の間の型変換はできません。

パラメータの取得に成功し、かつ型変換でエラーが発生しなかった場合は この関数は SUCCESS を返します。それ以外の場合は FAILURE を返します。また、 「パラメータの数が一致しない」「型変換ができなかった」 などの情報を含むエラーメッセージを出力します。

出力されるエラーメッセージは、例えば次のようなものになります。

型を指定する文字の一覧をここにまとめます。

• l - long

• d - double

• s - string (null バイトの可能性もあり) およびその長さ

• b - boolean

• r - zval* に保存されたリソース

• a - zval* に保存された配列

• o - zval* に保存された (あらゆるクラスの) オブジェクト

• O - zval* に保存された (クラスエントリで指定されているクラスの) オブジェクト

• z - zval* 自体

以下の文字は、型指定文字列の中で特別な意味を持ちます。

• | - 残りのパラメータがオプションであることを表します。 これらのパラメータに対応する保存用変数は、 拡張モジュール自身によってデフォルト値で初期化されなければなりません。 なぜなら、パラメータが渡されていなければパース関数を通過しないからです。

• / - パラメータの後にこの文字を続けると、 そのパラメータに対して SEPARATE_ZVAL_IF_NOT_REF() をコールします。これにより、そのパラメータが参照でなければパラメータのコピーが作成されます。

• ! - パラメータの後にこの文字を続けると、 そのパラメータは指定した型あるいは NULL となります (a、o、O、r および z についてのみ適用可能)。 NULL 値が渡された場合は、 保存ポインタの値が NULL に設定されます。

この関数の使用法について説明するには、 実際の例を見ていただくのがいちばんでしょう。

/* long、文字列とその長さ、そして zval を受け取ります。*/
long l;
char *s;
int s_len;
zval *param;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,
                          "lsz", &l, &s, &s_len, &param) == FAILURE) {
    return;
}

/* my_ce で指定するクラスのオブジェクト、そしてオプションで double 値を受け取ります。*/
zval *obj;
double d = 0.5;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,
                          "O|d", &obj, my_ce, &d) == FAILURE) {
    return;
}

/* オブジェクト (あるいは null)、そして配列を受け取ります。
   オブジェクトに null が渡された場合、obj は NULL となります。*/
zval *obj;
zval *arr;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O!a", &obj, &arr) == FAILURE) {
    return;
}

/* 配列のコピーを受け取ります。*/
zval *arr;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/", &arr) == FAILURE) {
    return;
}

/* 最初の 3 つのパラメータのみを受け取ります (可変引数の関数の場合に有用です)。*/
zval *z;
zend_bool b;
zval *r;
if (zend_parse_parameters(3, "zbr!", &z, &b, &r) == FAILURE) {
    return;
}

最後の例で、ZEND_NUM_ARGS() を使用せずにパラメータ数を 3 としていることに注目しましょう。 こうすることで、可変引数の関数に対して最低限必要な引数の数を指定することができます。 もちろん、もし残りのパラメータについても処理したいのなら zend_get_parameters_array_ex() を使用してそれを取得しなければなりません。

拡張版のパース関数も存在します。 これは、追加のフラグを引数に指定することでその動きを制御します。

int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...);

現在は、渡すことのできるフラグは ZEND_PARSE_PARAMS_QUIET だけです。これを指定すると、処理中に発生したエラーメッセージを出力しないようになります。 これは、その関数がさまざまな形式の引数を受け取ることを想定しており、 独自のエラーメッセージで対応したい場合などに有用です。

例えば、3 つの long 値あるいは 3 つの文字列を受け取る関数は、 このようになります。

long l1, l2, l3;
char *s;
if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET,
                             ZEND_NUM_ARGS() TSRMLS_CC,
                             "lll", &l1, &l2, &l3) == SUCCESS) {
    /* long の場合 */
} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET,
                                    ZEND_NUM_ARGS(), "s", &s, &s_len) == SUCCESS) {
    /* 文字列の場合 */
} else {
    php_error(E_WARNING, "%s() takes either three long values or a string as argument",
              get_active_function_name(TSRMLS_C));
    return;
}

上で説明したいずれの場合についても、パラメータの取得処理は慎重に行いましょう。 これ以外の例については、PHP に同梱されている拡張モジュールのソースを 参考にしてください。便利な使用法がいろいろ発見できるでしょう。

引数の取得の古い方法 (廃止予定)

注意: 廃止予定のパラメータパース用 API
この API は非推奨です。現在は新しい ZEND パラメータパース API が使用されています。

引数の数をチェックし終えたら、次は引数そのものにアクセスしなければなりません。 そのためには zend_get_parameters_ex() の助けを借りることになります。

zval **parameter;

if(zend_get_parameters_ex(1, &parameter) != SUCCESS)
  WRONG_PARAM_COUNT;

すべての引数は zval コンテナに格納され、 二重にポイントされる必要があります。 上のコードは、引数を取得してそれをポインタ parameter でアクセスできるようにしています。

zend_get_parameters_ex() は、少なくとも 2 つの引数を受け付けます。 最初の引数は、取得する引数の数です (これは、 関数がコールされた際の引数の数と同じでなければなりません。 そのため、呼び出し構文をきちんとチェックすることが大切になります)。 2 番目 (およびそれ以降) の引数は、zval へのポインタへのポインタへのポインタ (なんてややこしいことでしょう!) です。 これが必要になるのは、私たちが作成した関数内のローカル **zval を管理するために Zend は内部で **zval を使用しており、 zend_get_parameters_ex() はそれに対するポインタを必要とするからです。

zend_get_parameters_ex() の返り値は SUCCESS あるいは FAILURE で、それぞれ (当然のごとく) 成功したこと、あるいは引数の処理に失敗したことを示します。 もっともありがちな失敗の原因は、パラメータの数を間違えることです。 この場合は、 WRONG_PARAM_COUNT で関数を抜けなければなりません。

複数の引数を受け取るには、このようにします。

zval **param1, **param2, **param3, **param4;
     
if(zend_get_parameters_ex(4, &param1, &param2, &param3, &param4) != SUCCESS)
    WRONG_PARAM_COUNT;

zend_get_parameters_ex() がエラーとなるのは、 実際の数より多くのパラメータを取得しようとした場合のみです。 もし実際の関数が 5 つの引数でコールされたのに zend_get_parameters_ex() では 3 つしか取得しなかった場合、 何もエラーは発生せず、最初の 3 つのパラメータが取得されます。 続けて zend_get_parameters_ex() をコールしたとしても、 残りの引数が取得できるわけではなく最初と同じものが得られるだけです。

可変引数 / オプションパラメータの扱い

もしあなたの関数が可変引数を受け付けるのなら、 さきほどの例が次善の策となることもあるでしょう。ただ、 取りうる可能性のあるすべての引数の数に対して、それぞれ zend_get_parameters_ex() コールしなければならず、 不満が残ります。

このような場合には、 zend_get_parameters_array_ex() 関数を使うことができます。 これは、引数の数を指定してデータを取得し、それを配列に格納します。

zval **parameter_array[4];

/* 引数の数を取得します */
argument_count = ZEND_NUM_ARGS();

/* 引数の数の範囲 (最低 2 個、最大 4 個) */
/* を満たしているかどうかを調べます      */
if(argument_count < 2 || argument_count > 4)
    WRONG_PARAM_COUNT;

/* 引数の数が正しかったので、その内容を取得します */
if(zend_get_parameters_array_ex(argument_count, parameter_array) != SUCCESS)
    WRONG_PARAM_COUNT;

まず、引数の数を調べてそれが予期する範囲内にあることを確かめます。 それから zend_get_parameters_array_ex() を使用し、 引数の値へのポインタを parameter_array に格納します。

これを非常にうまく実装したのが、PHP の fsockopen() を処理するコードです。このコードは ext/standard/fsock.c にあり、 Zend API: PHP のコアをハックする で見ることができます。 このソースの中に知らない関数が含まれていたとしても、現時点では問題ありません。 すぐにわかるようになります。

pval **args[5];
int *sock=emalloc(sizeof(int));
int *sockp;
int arg_count=ARG_COUNT(ht);
int socketd = -1;
unsigned char udp = 0;
struct timeval timeout = { 60, 0 };
unsigned short portno;
unsigned long conv;
char *key = NULL;
FLS_FETCH();

if (arg_count > 5 || arg_count < 2 || zend_get_parameters_array_ex(arg_count,args)==FAILURE) {
    CLOSE_SOCK(1);
    WRONG_PARAM_COUNT;
}

switch(arg_count) {
    case 5:
        convert_to_double_ex(args[4]);
        conv = (unsigned long) (Z_DVAL_PP(args[4]) * 1000000.0);
        timeout.tv_sec = conv / 1000000;
        timeout.tv_usec = conv % 1000000;
        /* fall-through */
    case 4:
        if (!PZVAL_IS_REF(*args[3])) {
            php_error(E_WARNING,"error string argument to fsockopen not passed by reference");
        }
        pval_copy_constructor(*args[3]);
        ZVAL_EMPTY_STRING(*args[3]);
        /* fall-through */
    case 3:
        if (!PZVAL_IS_REF(*args[2])) {
            php_error(E_WARNING,"error argument to fsockopen not passed by reference");
            return;
        }
        ZVAL_LONG(*args[2], 0);
        break;
}

convert_to_string_ex(args[0]);
convert_to_long_ex(args[1]);
portno = (unsigned short) Z_LVAL_P(args[1]);

key = emalloc(Z_STRLEN_P(args[0]) + 10);

fsockopen() が受け付ける引数の数は、 2、3、4、あるいは 5 です。お決まりの変数宣言の後に、 この関数は引数の数が範囲内にあるかどうかを調べます。 それから、switch() 文の下に流れていく性質を利用して、 すべての引数を処理します。switch() 文は、 まず引数の数が最大 (5 個) であった場合の処理から始まります。 その後、引数の数が 4 個であった場合の処理、3 個であった場合の処理、 と順にたどっていきます。これは、キーワード break の記述を省略しているからです。最後の処理を実行した後で switch() 文は終了し、 関数の引数が 2 個だけであった場合でも、必要最小限の処理が実行されます。

このように複数ステージの処理を段階的に実行するようにすると、 可変引数の処理がやりやすくなります。

引数へのアクセス

引数にアクセスするには、すべての引数の型がきちんと定義されていなければなりません。 何度も言いますが、PHP は究極の動的言語なので、時に問題が起こることがあります。 PHP は一切の型チェックを行わないので、 どんな型のデータでも関数に渡すことができてしまいます。 本当は整数値を期待しているのに配列が渡されるかもしれないし、 その逆だってありえます。PHP は、こんな場合でも一切なにも通知しません。

これを防ぐには、これらの API を使用して引数の方を強制的に変換しなければなりません (Zend API: PHP のコアをハックする を参照ください)。

注意: すべての変換関数のパラメータは **zval です。

注意: これらの振る舞いのデモが、付録 CD-ROM の cross_conversion.php で見られます。

引数に対してこれらの関数を使用することで、 渡されたデータの型の安全性を確保できます。 渡された型が要求と異なった場合、PHP は空の値 (空の文字列、配列、オブジェクトや 数値の 0、Boolean の FALSE など) を結果として返します。

これは、先ほど説明したサンプルモジュールのコードの一部を引用したものです。 ここで実際に変換関数を使用しています。

zval **parameter;

if((ZEND_NUM_ARGS() != 1) || (zend_get_parameters_ex(1, &parameter) != SUCCESS))
{
    WRONG_PARAM_COUNT;
}

convert_to_long_ex(parameter);

RETURN_LONG(Z_LVAL_P(parameter));

パラメータへのポインタを取得した後に、パラメータの値が long 型 (整数値) に変換されます。そしてそれがこの関数の返り値となります。 この値の中身にアクセスするには、zval 型についての知識が必要です。その定義を Zend API: PHP のコアをハックする に示します。

typedef pval zval;
     
typedef struct _zval_struct zval;

typedef union _zvalue_value {
    long lval;                 /* long 値 */
    double dval;               /* double 値 */
    struct {
        char *val;
        int len;
    } str;
    HashTable *ht;             /* ハッシュテーブル値 */
    struct {
        zend_class_entry *ce;
        HashTable *properties;
    } obj;
} zvalue_value;

struct _zval_struct {
    /* 変数の情報 */
    zvalue_value value;        /* 値 */
    unsigned char type;        /* アクティブな型 */
    unsigned char is_ref;
    short refcount;
};

実際のところは pval (php.h で定義) は単なる zval (zend.h で定義) のエイリアスであり、これは _zval_struct をさしています。 そこで、この構造体に注目してみましょう。 _zval_struct は「マスタ」構造体であり、 その中には値情報、型情報、参照情報が含まれています。 中に含まれている zvalue_value は共用体であり、 変数の値がそこに含まれます。変数の型に応じて、共用体の中の適切なメンバーにアクセスする必要があります。 それぞれの構造体については Zend API: PHP のコアをハックする、 Zend API: PHP のコアをハックする および Zend API: PHP のコアをハックする を参照ください。

long 値にアクセスするには zval.value.lval、 double 値にアクセスするには zval.value.dval、といったように使用します。 すべての値は共用体に保存されるので、不適切なメンバーにアクセスすると、 無意味な結果を得ることになります。

配列やオブジェクトへのアクセスは少し複雑なので、後で説明します。

参照渡しされた引数の扱い

参照渡しの引数を受け取って関数内部でそれを変更しようとする場合は、 少々注意が必要です。

敢えて説明しませんでしたが、ここで示している状況では、 関数のパラメータとして受け取った zval に対する書き込み権限はありません。 もちろん関数内で独自に作成した zval を変更することは可能ですが、 Zend の内部データを参照している zval は、 決して変更してはいけません。

これまで説明してきたのは、いわゆる *_ex() 系の API ばかりです。お気づきかもしれませんが、これまで使用してきた API 関数は zend_get_parameters() ではなくて zend_get_parameters_ex() でしたし、また convert_to_long() ではなくて convert_to_long_ex() でした。これらの *_ex() 系の関数は、いわゆる「拡張」Zend API と呼ばれるものです。 これらは、以前の API に比べて速度が少し向上しているのですが、 それと引き換えに読み込み専用のアクセスしかできないようになっています。

Zend は内部的には参照を使用しているので、 さまざまな変数が同じ値を参照することもありえます。 zval コンテナへの書き込みアクセスをするためには、 このコンテナが保持する値が他と完全に分離していること、 つまり他のコンテナから参照されていないことが必要です。 zval コンテナが他のコンテナから参照されている場合に その zval を変更すると、この zval を参照しているその他のコンテナの内容も変わってしまいます (それらも変更後の値を指すようになるからです)。

zend_get_parameters_ex() は、単に zval コンテナへのポインタを返します。そこに参照が含まれているかどうかは考慮しません。 一方、これに対応する伝統的な API である zend_get_parameters() は、参照をチェックします。 参照が見つかった場合には、独立した zval コンテナを新しく作成し、参照先のデータをそこにコピーし、 その新しく作成した (他とは分離している) コンテナへのポインタを返します。

この操作のことを zval separation (zval の分離) (あるいは pval separation) と言います。*_ex() API は zval の分離を行わないません。そのために大幅に高速化されましたが、 その代償として書き込みアクセスができなくなっています。

とは言うものの、パラメータを変更するには書き込みアクセスをしなければなりません。 このような場合のために、Zend には特別な方法が用意されています。 関数のパラメータが参照渡しされた場合は、自動的に zval の分離が行われるのです。 つまり、PHP で下のように関数をコールすると、$parameter が独立した値として渡されることを Zend が自動的に保証してくれるのです。 これにより、書き込みが可能となります。

my_function(&$parameter);

しかし、これは値渡しのパラメータには適用されません! 参照渡し以外で渡されたパラメータ以外は、読み込み専用となります。

これらの性質により、パラメータを扱う際にはそれが参照なのかそうでないのかをしっかり見極める必要があります。 さもないと、思ってもいない結果を引き起こすことになります。 パラメータが参照渡しされたかどうかを調べるためには、マクロ PZVAL_IS_REF を使用します。このマクロは zval* を受け取り、それが参照かそうでないかを返します。 Zend API: PHP のコアをハックする に実際の使用例があります。

例8 パラメータが参照で渡されたかどうかを調べる

zval *parameter;

if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z", &parameter) == FAILURE)
    return;

/* パラメータが参照で渡されたかどうかを調べます */
if (!PZVAL_IS_REF(parameter)) {
{
    zend_error(E_WARNING, "パラメータは参照渡しされませんでした");
    RETURN_NULL();
}

/* パラメータを変更します */
ZVAL_LONG(parameter, 10);

その他のパラメータの書き込みについての安全性の保障

zend_get_parameters_ex() で取得したパラメータのうち、 参照渡しではないものについても値を変更したくなる場合があるかもしれません。 そんなときには、マクロ SEPARATE_ZVAL を使用します。 これは、指定したコンテナについて zval の分離を行います。 新しく作成された zval は内部のデータとは分離されており、 ローカルスコープでしか使用できません。つまり、 スクリプト全体のコンテキストに影響を与えることなく データを変更したり破壊したりできるようになるのです。

zval **parameter;
     
/* パラメータを取得します */
zend_get_parameters_ex(1, &parameter);

/* この時点では、<parameter> はまだ          */
/* Zend の内部データバッファと紐付いています */

/* <parameter> を書き込み可能にします */
SEPARATE_ZVAL(parameter);

/* この時点で、<parameter> が変更できるようになります。*/
/* グローバルに影響を与えることはありません            */

SEPARATE_ZVAL は、emalloc() を使用して新しい zval コンテナを確保します。 つまり、このメモリの開放を忘れてしまったとしても、 スクリプトの終了時に自動的に破棄されるということです。 しかし、コンテナを開放せずにこのマクロをコールし続けると、 RAM が散らかってしまいます。

注意: 書き込み権限の問題については、 「伝統的な」API (zend_get_parameters() やその他) を使用すれば簡単に回避できます。しかし、この API は非推奨のようなので、今後この章では深入りしません。

概要

実行中のスクリプトによって「外部から」見える変数を新しく作成するには、 まず新しい zval コンテナを確保してそこに値を格納し、 それを Zend の内部シンボルテーブルに登録しなければなりません。 これは、変数を作成する際のお決まりの手順です。

zval *new_variable; 

/* 新しいコンテナを確保して初期化します */
MAKE_STD_ZVAL(new_variable); 

/* 型や値をここで設定します。これ以降の節を参照ください */ 

/* この変数を "new_variable_name" という名前でシンボルテーブルに登録します */
ZEND_SET_SYMBOL(EG(active_symbol_table), "new_variable_name", new_variable); 

/* これで、$new_variable_name という名前でスクリプトからアクセスできるようになります */

マクロ MAKE_STD_ZVAL は、ALLOC_ZVAL を使用して新しい zval コンテナを確保し、 INIT_ZVAL でそれを初期化します。 これを書いている時点の Zend の実装では、初期化 というのは参照カウンタを 1 にして is_ref フラグをクリアすることを指します。 しかし、これは今後拡張される可能性があります。そのため、 ALLOC_ZVAL を直接使用するのではなく MAKE_STD_ZVAL を用いるようにしておくことが大切です。 実行速度を最適化したい場合 (そして、ここで明示的に zval コンテナを初期化する必要がない場合) は ALLOC_ZVAL を使用することも可能です。 しかし、データの整合性を保証できなくなるため、 この方法は推奨されません。

ZEND_SET_SYMBOL の役割は、新しい変数を Zend のシンボルテーブルに登録することです。このマクロは、 その値が既にシンボルテーブルに存在するかどうかを調べ、 もし存在すれば新しいシンボルを参照に変換します (古い zval コンテナが使用していたメモリは、 自動的に開放されます)。速度を気にする必要がない場合には この方法がお勧めです。メモリの使用量を抑えることができます。

ZEND_SET_SYMBOL は、マクロ EG 経由で Zend executor のグローバル変数を使用することに注意しましょう。 EG(active_symbol_table) を指定することで、 現在アクティブなシンボルテーブルを、アクティブなローカルスコープで扱えるようになります。 ローカルスコープは、その関数が関数内でコールされたかどうかによって異なります。

とにかく速度を最適化したい、メモリの消費量はあまり気にしない という場合には、同じ値が既存の変数に登録されているかどうかの チェックを省略することができます。その代わりに、 zend_hash_update() を使用して 強制的にシンボルテーブルに挿入します。

zval *new_variable;

/* 新しいコンテナを確保して初期化します */
MAKE_STD_ZVAL(new_variable);

/* 型や値をここで設定します。これ以降の節を参照ください */ 

/* この変数を "new_variable_name" という名前でシンボルテーブルに登録します */
zend_hash_update(
    EG(active_symbol_table),
    "new_variable_name",
    strlen("new_variable_name") + 1,
    &new_variable,
    sizeof(zval *),
    NULL
);

これは、ほとんどのモジュールで使用されている標準的な方法です。

上の例で作成された変数は、常にローカルスコープにあります。 つまり、その関数がコールされたコンテキスト内に存在するということです。 新しい変数をグローバルスコープに作成するにも同じメソッドを使用しますが、 別のシンボルテーブルを参照します。

zval *new_variable;
     
// 新しいコンテナを確保して初期化します
MAKE_STD_ZVAL(new_variable);

//
// 型や値をここで設定します
//

// この変数を "new_variable_name" という名前でグローバルシンボルテーブルに登録します
ZEND_SET_SYMBOL(&EG(symbol_table), "new_variable_name", new_variable);

今回は、EG(symbol_table) によって参照される本体のグローバルシンボルテーブルを使用して ZEND_SET_SYMBOL マクロがコールされています。

注意: 変数 active_symbol_table はポインタですが、symbol_table はそうではありません。 これは、 EG(active_symbol_table) および &EG(symbol_table) を ZEND_SET_SYMBOL へのパラメータとして使用する必要があるからです - ここにはポインタが必要です。

同様に、より効率的なバージョンとして、 シンボルテーブルの更新をハードコーディングすることもできます。

zval *new_variable;

// 新しいコンテナを確保して初期化します
MAKE_STD_ZVAL(new_variable);

//
// 型や値をここで設定します
//

// この変数を "new_variable_name" という名前でグローバルシンボルテーブルに登録します
zend_hash_update(
    &EG(symbol_table),
    "new_variable_name",
    strlen("new_variable_name") + 1,
    &new_variable,
    sizeof(zval *),
    NULL
);

Zend API: PHP のコアをハックする は、ふたつの変数を作成する例です。 local_variable はローカルスコープ、そして global_variable はグローバルスコープとなります (図 9.7 を参照ください)。完全な例は CD-ROM にあります。

注意: グローバル変数は、実際には関数内からアクセスできないことにお気づきでしょう。 これは、PHP ソース内で global $global_variable; のようにローカルスコープにインポートしていないからです。

例9 スコープが異なる変数の作成

ZEND_FUNCTION(variable_creation)
{
    zval *new_var1, *new_var2;

    MAKE_STD_ZVAL(new_var1);
    MAKE_STD_ZVAL(new_var2);

    ZVAL_LONG(new_var1, 10);
    ZVAL_LONG(new_var2, 5);

    ZEND_SET_SYMBOL(EG(active_symbol_table), "local_variable", new_var1);
    ZEND_SET_SYMBOL(&EG(symbol_table), "global_variable", new_var2);

    RETURN_NULL();

}

Long (整数型)

さあ、それではデータを変数に代入していきましょう。まずは long 型からです。long は PHP の整数型で、非常にシンプルな形式で保存されます。 この章の最初のほうで説明した zval.value コンテナの 構造を見てみましょう。long 型のデータは、共用体の lval フィールドに直接格納されることがおわかりでしょう。 long 型に対応する type の値は IS_LONG です (Zend API: PHP のコアをハックする を参照ください)。

zval *new_long;

MAKE_STD_ZVAL(new_long);

new_long->type = IS_LONG;
new_long->value.lval = 10;

あるいは、マクロ ZVAL_LONG を使用することもできます。

zval *new_long;

MAKE_STD_ZVAL(new_long);
ZVAL_LONG(new_long, 10);

Double (浮動小数点型)

double 型は PHP の浮動小数点型で、long 型と同様に簡単に代入できます。 この値もまた共用体に直接格納されるからです。 zval.value コンテナで対応するメンバは dval です。また、対応する type は IS_DOUBLE となります。

zval *new_double;

MAKE_STD_ZVAL(new_double);

new_double->type = IS_DOUBLE;
new_double->value.dval = 3.45;

あるいは、マクロ ZVAL_DOUBLE を使用することもできます。

zval *new_double;

MAKE_STD_ZVAL(new_double);
ZVAL_DOUBLE(new_double, 3.45);

文字列

文字列についてはもう少し手間を掛けなければなりません。 先に説明したように、Zend の内部データ構造に関連付けられる すべての文字列は、Zend 自身のメモリ管理関数を使用して管理しなければなりません。 静的な文字列を参照したり、標準関数を使用して割り当てた文字列を使用することはできません。 文字列を代入するには、zval.value コンテナの構造体 str にアクセスしなければなりません。 対応する type は IS_STRING です。

zval *new_string;
char *string_contents = "This is a new string variable";

MAKE_STD_ZVAL(new_string);

new_string->type = IS_STRING;
new_string->value.str.len = strlen(string_contents);
new_string->value.str.val = estrdup(string_contents);

ここでの、Zend の estrdup() の使用法に注意しましょう。 もちろん、定義済みのマクロ ZVAL_STRING を使用することも可能です。

zval *new_string;
char *string_contents = "This is a new string variable";

MAKE_STD_ZVAL(new_string);
ZVAL_STRING(new_string, string_contents, 1);

ZVAL_STRING は、3 番目のパラメータをとることができます。 これは、指定した文字列が (estrdup() を使用して) 複製されるべきかどうかを指定します。このパラメータに 1 を指定すると、文字列が複製されます。 0 の場合は、渡されたポインタを そのまま変数の内容として使用します。これは、すでに Zend の内部メモリに割り当てられている文字列を参照する変数を 作成する場合に便利です。

ある場所で文字列を切り捨てたい場合、 あるいは文字列の長さが事前にわかっている場合は、ZVAL_STRINGL(zval, string, length, duplicate) を使用して 新しい文字列の長さを明示的に指定することができます。 このマクロは ZVAL_STRING より高速に動作し、 バイナリセーフです。

空の文字列を作成するには、文字列の長さを 0 にしたうえで、中身に empty_string を使用します。

new_string->type = IS_STRING;
new_string->value.str.len = 0;
new_string->value.str.val = empty_string;

もちろん、これを行うためのマクロもあります (ZVAL_EMPTY_STRING)。

MAKE_STD_ZVAL(new_string);
ZVAL_EMPTY_STRING(new_string);

論理型

論理型の作り方は long 型と同じです。ただ、type は IS_BOOL となります。 lval に指定できる値は 0 および 1 です。

zval *new_bool;

MAKE_STD_ZVAL(new_bool);

new_bool->type = IS_BOOL;
new_bool->value.lval = 1;

この型に対応するマクロは ZVAL_BOOL (値を指定できます)、そして ZVAL_TRUE および ZVAL_FALSE (それぞれ、値を明示的に TRUE および FALSE に設定します) です。

配列

配列は、Zend の内部ハッシュテーブルに格納されます。 このハッシュテーブルにアクセスするには zend_hash_*() API を使用します。配列を作成するたびに、新しいハッシュテーブルの ハンドルが必要となります。これは、zval.value コンテナのメンバ ht に格納されます。

単に配列を作成するためだけの API があります。これは非常に便利です。 新しい配列を開始するには、array_init() をコールします。

zval *new_array;

MAKE_STD_ZVAL(new_array);

array_init(new_array);

array_init() は、常に SUCCESS を返します。

配列に新しい要素を追加するには、 やりたいことに応じてさまざまな関数を使用できます。 Zend API: PHP のコアをハックする、 Zend API: PHP のコアをハックする および Zend API: PHP のコアをハックする で、これらの関数について説明しています。これらの関数はすべて、 失敗した場合に FAILURE、 成功した場合に SUCCESS を返します。

これらの関数はすべて、Zend 内部のハッシュ API を抽象化して使用しやすくしたものです。 もちろん、ハッシュ関数を直接使用することも可能です。例えば、すでに割り当て済みの zval コンテナを配列に挿入する場合などが考えられます。 これを行うには、連想配列の場合は zend_hash_update() (Zend API: PHP のコアをハックする を参照ください)、 数値添字配列の場合は zend_hash_index_update() (Zend API: PHP のコアをハックする を参照ください) を使用します。

zval *new_array, *new_element;
char *key = "element_key";
      
MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);

array_init(new_array);

ZVAL_LONG(new_element, 10);

if(zend_hash_update(new_array->value.ht, key, strlen(key) + 1, (void *)&new_element, sizeof(zval *), NULL) == FAILURE)
{
    // エラー処理をここで行います
}

zval *new_array, *new_element;
int key = 2;

MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);

array_init(new_array);

ZVAL_LONG(new_element, 10);

if(zend_hash_index_update(new_array->value.ht, key, (void *)&new_element, sizeof(zval *), NULL) == FAILURE)
{
    // エラー処理をここで行います
}

add_next_index_*() の機能をエミュレートするには、 これを使用します。

zend_hash_next_index_insert(ht, zval **new_element, sizeof(zval *), NULL)

注意: 関数から配列を返すには、まず array_init() を使用し、それ以降の操作は定義済み変数 return_value で行います (エクスポートする関数への引数として渡します。 呼び出しインターフェイスについての先ほどの議論を参照ください)。 ここで MAKE_STD_ZVAL を使用してはいけません。

Tip: 毎回 new_array->value.ht を書く手間を省くためには HASH_OF(new_array) を使用します。 これは、互換性やコーディングスタイルの観点からもお勧めです。

オブジェクト

オブジェクトは配列に変換できる (その逆も可能) ので、 PHP の配列と多くの共通点があるであろうことはお気づきでしょう。 オブジェクトを処理するには、同じようなハッシュ関数を使用しますが、 オブジェクトを作成する際には異なる API を使用します。

オブジェクトを初期化するには、関数 object_init() を使用します。

zval *new_object;

MAKE_STD_ZVAL(new_object);

if(object_init(new_object) != SUCCESS)
{
    // エラー処理をここで行います
}

Zend API: PHP のコアをハックする で説明している関数を使用すると、 オブジェクトにメンバを追加することができます。

リソース

リソースは、PHP における特殊なデータ型です。 リソース (resources) は何らかの特定の型を表すわけではなく、 さまざまな情報を扱うための抽象化した方法を表しています。 リソースは、Zend の内部では特別なリストの中に保持されます。 リストの各エントリは、そのリソースが指すデータを表す型定義を持っています。 Zend は、内部でリソースを扱う際には、常にこれを使用します。 リソースに直接アクセスすることはできず、提供されている API を通じてアクセスしなければなりません。特定のリソースに対する 参照がすべて失われると、対応するシャットダウン関数がすぐにコールされます。

例えば、リソースは、 データベースへのリンクやファイル記述子を格納するために使用されます。 事実上の標準実装となっているのは MySQL モジュールです。しかし、例えば Oracle モジュールのような その他のモジュールでもリソースを使用しています。

注意: 実際のところ、あなたが関数内で処理したい任意のデータへのポインタ (例: 構造体へのポインタ) を、リソースとして使用することができます。 ユーザがこのデータにアクセスするには、ひとつのリソース変数を 関数に渡すだけでいいようになります。

新しいリソースを作成するには、そのリソースを開放するためのハンドラを 登録しなければなりません。リソースにはあらゆる種類のデータを保存できるので、 Zend は、それが不要になった際にどのように開放するのかを知っておく必要があるのです。 これを実現するために、自分が作成したリソース開放ハンドラを Zend に登録します。これは、(手動・自動にかかわらず) リソースを開放することになった際に、Zend によってコールされます。 リソースハンドラを Zend に登録すると、そのリソースについての リソース型ハンドルが Zend から返されます。 このハンドルは、後でこの型のリソースにアクセスする際には常に必要となり、 たいていは拡張モジュール内のグローバルな静的変数として保存されます。 スレッドセーフであるかどうかについて心配する必要はありません。 なぜなら、リソースハンドラの登録は モジュールの初期化時に一度行うだけだからです。

リソースハンドラを登録するための Zend の関数は、次のように宣言されています。

ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, char *type_name, int module_number);

この関数には、二種類の異なるリソース破壊ハンドラを渡すことが可能です。 それぞれ、通常のリソース用のものと持続的なリソース用のものになります。 持続的なリソースとは、例えばデータベース接続などに使用されるものです。 リソースを登録する際には、これらのどちらかのハンドラを必ず指定しなければなりません。 もう一方のほうには、単に NULL を渡すようにします。

zend_register_list_destructors_ex() は、次のパラメータを受け取ります。

返り値は、作成した リソース型 の一意な ID となる整数値です。

リソース破壊ハンドラ (通常版および持続的リソース版のどちらも) のプロトタイプは次のようになります。

rsrc に渡されるのは、次のような構造体へのポインタです。

typedef struct _zend_rsrc_list_entry {
     
    void *ptr;
    int type;
    int refcount;

} zend_rsrc_list_entry;

メンバ void *ptr が、 リソースへの実際のポインタとなります。

これでやるべきことがわかりました。Zend に登録したいリソースを、 実際に定義してみましょう。 ここでは、ふたつの整数型メンバからなる単純な構造体を考えます。

typedef struct {
     
    int resource_link;
    int resource_type;

} my_resource;

このリソースを破壊するハンドラは、おそらく次のようなものとなるでしょう。

void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {

    // たいていは void ポインタを構造体の型にキャストすることになるでしょう。

    my_resource *my_rsrc = (my_resource *) rsrc->ptr;

    // ここで、そのリソースに対して必要な作業を行います。たとえば
    // ファイルやソケットを閉じたり、内部で新たに確保したメモリを開放したりなどです。
    // もちろん、このリソース自身が使っているメモリを開放することも忘れないようにしましょう。

    do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
}

注意: 注意すべき点: もしそのリソースが複雑な構造体であり、 その内部で実行時に確保したメモリへのポインタを含んでいる場合は、 リソース自身のメモリを開放する 前に 実行時に確保したメモリを開放しなければなりません。

ここまでで、

1. どんなリソースなのか

2. そのリソースを破壊する際のハンドラ

の定義が終了しました。それでは残りの作業を進めましょう。

1. 拡張モジュール内のグローバル変数を作成し、 リソース ID を保持させる。必要に応じて、 これは全ての関数からアクセス可能となる

2. リソース名を定義する

3. リソース破壊ハンドラを記述する

4. そしてそのハンドラを登録する

// 拡張モジュール内のどこかで、登録したリソース用の変数を定義します。
    // 'le' って何のことだって? 単に 'list entry' を略しただけです。
    static int le_myresource;

    // リソース名もどこかで定義しておくとよいでしょう。
    #define le_myresource_name  "My type of resource"

    [...]

    // 実際にリソース破壊ハンドラを登録します。
    void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {

        my_resource *my_rsrc = (my_resource *) rsrc->ptr;
        do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
    }

    [...]

    PHP_MINIT_FUNCTION(my_extension) {

        // 'module_number' は、PHP_MINIT_FUNCTION() 関数の
        // 定義で既に提供されていることに注意しましょう。

        le_myresource = zend_register_list_destructors_ex(my_destruction_handler, NULL, le_myresource_name, module_number);

        // 別のリソースを登録したり、グローバル変数や定数を
        // 初期化したりします。
    }

実際に新しいリソースを登録するには、 zend_register_resource() 関数あるいは ZEND_REGISTER_RESOURE() マクロのいずれかを使用します。 これらはどちらも zend_list.h で定義されています。 それぞれの引数は一対一対応しているので、 将来の互換性を考えると常にマクロを使用するようにすることをお勧めします。

int ZEND_REGISTER_RESOURCE(zval *rsrc_result, void *rsrc_pointer, int rsrc_type);

返り値は、そのリソースに対応する一意な整数値になります。

新しいリソースを登録する際に実際には何が行われているのかというと、 まずそれが Zend の内部リストに挿入されます。そして、 結果は単に与えられた zval * コンテナに保存されます。

rsrc_id = zend_list_insert(rsrc_pointer, rsrc_type);
     
    if (rsrc_result) {
        rsrc_result->value.lval = rsrc_id;
        rsrc_result->type = IS_RESOURCE;
    }

    return rsrc_id;

返される rsrc_id は、 新しく登録されたリソースを表す一意な識別子となります。 マクロ RETURN_RESOURE を使用して、 これを利用者に返すことができます。

注意: そのリソースをすぐに利用者に返したいのなら、 return_value を zval * コンテナに設定するのが一般的な方法です。

Zend はこれ以降、このリソースに対するすべての参照を管理できるようになります。 リソースへの参照がすべて失われると、リソースに対して事前に定義した デストラクタがすぐにコールされます。この設定の利点は、 あなたのモジュール内で発生するメモリリークを気にしなくてもすむということです。 呼び出し元スクリプトで割り当てているすべてのメモリはリソースを参照しています。 メモリが必要なくなったとスクリプトが判断した時点で、 Zend はすぐにそれを検出して通知してくれます。

さて、利用者がリソースを取得したあとで、 それをまたあなたの作成した関数に渡してきたとしましょう。 zval * コンテナ内の value.lval にはあなたのリソースのキーが含まれているので、 それを使用して次のマクロでリソースを取得することができます。 ZEND_FETCH_RESOURCE:

ZEND_FETCH_RESOURCE(rsrc, rsrc_type, rsrc_id, default_rsrc_id, resource_type_name, resource_type)

このマクロは何も値を返しません。これは開発者の利便性のためで、 TSRMLS 引数のことを考慮したものです。リソースを読み込む段階でチェックが行われます。 リソースの取得時にエラーが発生した場合は、このマクロは 警告メッセージをスローし、PHP 関数は NULL を返します。

リソースをリストから強制的に削除するには、関数 zend_list_delete() を使用します。 また事前に割り当てた値への新たな参照を作成した場合 (例えば、デフォルトのデータベースリンクを再利用する場合) などは、強制的に参照カウンタを増加させることができます。 このような場合は、関数 zend_list_addref() を使用します。事前に割り当てたリソースエントリを探すには zend_list_find() を使用します。 これらの完全な API は、zend_list.h で確認できます。

自動グローバル変数の作成のためのマクロ

先ほど説明したマクロに加え、 単純なグローバル変数を簡単に作成するためのマクロがあります。 これらは、例えばグローバルなフラグなどを作成する際に知っておくと便利です。 あまり行儀のよいやり方ではありませんが、 Zend API: PHP のコアをハックする で説明するマクロはまさにこの作業を行うためのものです。 これらは zval を確保する必要がありません。 単純に、変数名と値を渡すだけでいいのです。

定数の作成

Zend は (通常の変数ではなく) 真の定数の作成もサポートしています。 定数へのアクセスにはドル記号 ($) の接頭辞が不要で、すべてのスコープで使用可能です。 例としては TRUE や FALSE などがあります。

独自の定数を作成するには、 Zend API: PHP のコアをハックする のマクロを使用します。 これらのマクロは、指定した名前と値の定数を作成します。

各定数に対して、フラグを指定することもできます。

• CONST_CS - この定数名は、大文字小文字を区別して扱われます。

• CONST_PERSISTENT - この定数は持続的に扱われ、この定数を保持しているプロセスが 終了した後も「忘れられる」ことはありません。

これらのフラグは、OR で組み合わせて使用します。

マクロには、ふたつの形式があります。 REGISTER_*_CONSTANT および REGISTER_MAIN_*_CONSTANT です。 最初の形式は、定数を現在のモジュールにバインドします。 これらの定数は、そのモジュールがメモリから開放されるとすぐに、 シンボルテーブルから削除されます。二番目の形式が作成する定数は、 モジュールとは独立してシンボルテーブルに残り続けます。

zend_printf()

zend_printf() は、標準の printf() と同じような動作をしますが、 出力先が Zend の出力ストリームとなります。

zend_error()

zend_error() は、エラーメッセージを生成するために使用します。 この関数は 2 つの引数を受け取ります。最初の引数はエラーの型 (zend_errors.h を参照ください)、 そして 2 番目の引数がエラーメッセージとなります。

zend_error(E_WARNING, "This function has been called with empty arguments");

指定できる値を Zend API: PHP のコアをハックする にまとめます (以下 を参照ください)。 これらの値は、php.ini でも参照されます。 選んだ型によっては、エラーメッセージがログに記録されます。

phpinfo() の出力内容

実際にモジュールを作成してみると、そのモジュールについての情報を phpinfo() に表示してみたくなるでしょう (モジュール名だけは、モジュール一覧のところにデフォルトで表示されます)。 PHP allows you to create your own section in the phpinfo() output with the ZEND_MINFO() function. この関数はモジュール記述子ブロック (先ほど説明しました) に配置しなければなりません。スクリプトが phpinfo() をコールした際には、常にこの関数がコールされます。

ZEND_MINFO 関数を指定すると、PHP は phpinfo() の出力に自動的にセクションを追加します。 ここには見出しとしてモジュール名が含められます。 それ以外のすべてはあなた自身が書式設定して表示する必要があります。

一般的には、まず php_info_print_table_start() を使用して HTML テーブルのヘッダを作成した後で、 標準関数 php_info_print_table_header() および php_info_print_table_row() を使用します。 これらの関数は、どちらも引数としてカラム数 (整数) とカラムの内容 (文字列) をとります。 Zend API: PHP のコアをハックする に、ソースの例とその出力を示します。 テーブルのフッタを表示するには、php_info_print_table_end() を使用します。

例13 ソースコードおよび phpinfo() の出力のスクリーンショット

php_info_print_table_start();
php_info_print_table_header(2, "First column", "Second column");
php_info_print_table_row(2, "Entry in first row", "Another entry");
php_info_print_table_row(2, "Just to fill", "another row here");
php_info_print_table_end();

実行時の情報

現在実行中のファイル名など、実行時の情報を表示することも可能です。 現在実行中の関数名を取得するには、関数 get_active_function_name() を使用します。 この関数は何も引数を受け取らず、関数名へのポインタを返します。 現在実行中のファイル名を取得するには、関数 zend_get_executed_filename() を使用します。 この関数は executor グローバルにアクセスします。これは TSRMLS_C マクロを使用して渡されます。 executor グローバルは、Zend から直接コールされたすべての関数 (この章で先ほど説明した INTERNAL_FUNCTION_PARAMETERS の一部です) で自動的に使用可能となります。 自動的に使用可能にならないような関数で executor グローバルにアクセスしたい場合は、 その関数内でいちど TSRMLS_FETCH() マクロをコールします。 これにより、グローバルの内容がローカルスコープに読み込まれます。

最後に、現在実行中の行番号を取得するには、関数 zend_get_executed_lineno() を使用します。 この関数も、引数として executor グローバルを受け取ります。 これらの関数の使用例については Zend API: PHP のコアをハックする を参照ください。

例14 実行時の情報の表示

zend_printf("The name of the current function is %s<br>", get_active_function_name(TSRMLS_C));
zend_printf("The file currently executed is %s<br>", zend_get_executed_filename(TSRMLS_C));
zend_printf("The current line being executed is %i<br>", zend_get_executed_lineno(TSRMLS_C));

config.m4

config.m4 は buildconf によって使用されます。 configure 時に実行する内容についてはすべてここで指示しておかなければなりません。 例えば、行うべきテストや必要な外部ファイル (ヘッダファイルなど) についての指示などがあてはまります。このために使用できるマクロが PHP で定義されています。その中でも最も有用なものを Zend API: PHP のコアをハックする にまとめます。