関数の作成

PHP では関数とメソッドはだいたい同じ形式で、メソッドは単にスコープが限定された関数でしかありません。 つまり、そのメソッドが属するクラスエントリのスコープになるということです。 クラスエントリについては、このマニュアルの別のページで説明します。 このセクションの目的は、関数やメソッドの内部構造を紹介することです。 関数を定義したり、変数を受け取ったり、PHP プログラマーに値を返したりする方法を説明します。

関数の内部構造は、それほど単純ではありません。

PHP_FUNCTION(hackers_function) {
  /* 受け取る引数をここで指定します */
  long number;
  
  /* 引数を受け取ります */
  if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &number) != SUCCESS) {
      return;
  }
  
  /* 何かの作業をします */
  number *= 2;
  
  /* 戻り値を設定します */
  RETURN_LONG(number);
}

プリプロセッサの PHP_FUNCTION(hackers_function) 命令は、 次のような宣言に展開されます。

void zif_hackers_function(INTERNAL_FUNCTION_PARAMETERS)

INTERNAL_FUNCTION_PARAMETERS はマクロとして定義されており、 次の表のようになります。

INTERNAL_FUNCTION_PARAMETERS
型と名前説明アクセス用マクロ
int htユーザーから実際に渡されたパラメータの数ZEND_NUM_ARGS()
zval *return_valuePHP 変数へのポインタ。ここに、ユーザーへの戻り値を設定します。 デフォルトの型は IS_NULL です。RETVAL_*, RETURN_*
zval **return_value_ptrPHP に参照を返すときには、ここに変数へのポインタを設定します。 参照を返すことはお勧めしません。 
zval *this_ptrメソッド呼び出しの場合は、$this オブジェクトを保持する PHP 変数を指します。getThis()
int return_value_used返り値を呼び出し元が使うかどうかを示すフラグ。 

明確にするために、完全に展開した PHP_FUNCTION(hackers_function) のドキュメントを示します。

void zif_hackers_function(int ht, zval* return_value, zval** return_value_ptr, zval* this_ptr, int return_value_used)

this_ptr の存在を奇妙に感じるかもしれません。クラスの詳細は後ほど説明するとして、ここでは PHP_METHOD(MyClass, hackersFunction) の結果が次のような宣言になることを示しておけば十分でしょう。

void zim_MyClass_hackersFunction(INTERNAL_FUNCTION_PARAMETERS)

hackers_function は特に凝ったことをするわけではなく、zend_parse_parameters API を使って受け取った数値を二倍して、それをエンジンに返すだけです。 普通は、単に入力を二倍するだけなどではなく、もっと複雑な何かを行うことでしょう。 ここでは、説明のために、できるだけシンプルにとどめました。 関数に入った際に return_value を確保し、null に初期化されます。 これで、PHP の関数のデフォルトの返り値が null となります。

Hacker が正しい引数として指定する内容を zend_parse_parameters が受け取れず、受け取った引数を type_spec を満たす形式に変換できなかった場合は、エラーを発生させます。 そして、Hacker はその場で return しなければいけません。

パラメータのプロトタイプのパース
int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...)
int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...)
int zend_parse_parameter(int flags, int arg_num TSRMLS_DC, zval **arg, const char *spec, ...)

これらの API 関数から受け取る可変引数は、C の変数のアドレスであることが期待されています。 また、zend_parse_parameters API 関数の出力であると考えなければいけません。

型指定子
指定子ローカル
aarrayzval*
Aarray あるいは objectzval*
bbooleanzend_bool
Cclasszend_class_entry*
ddoubledouble
ffunctionzend_fcall_info*, zend_fcall_info_cache*
harrayHashTable*
Harray あるいは objectHashTable*
llonglong
Llong (LONG_MAX/LONG_MIN の範囲に収まるもの)long
oobjectzval*
Oobject (指定した zend_class_entry のもの)zval*, zend_class_entry*
pstring (有効なパス)char*, int
rresourcezval*
sstringchar*, int
zmixedzval*
Zmixedzval**
高度な型指定子
指定子説明
*直前の型の引数が 0 個以上
+直前の型の引数が 1 個以上
|残りのパラメータは任意である
/後に続くパラメータを SEPARATE_ZVAL_IF_NOT_REF します。
!直前のパラメータが、指定した型あるいは null のどちらかになるものとします。 'b'、'l'、'd' の場合は、対応する bool*long*double* の後に zend_bool* 型の引数を追加する必要があります。null を受け取った場合は、ここに true が設定されます。

一度 Hacker の関数が実行されたら、実行するよう実装されているかどうかにかかわらず、エンジン向けの return_value を設定します。 RETURN_ マクロと RETVAL_ マクロは Z_*_P の単なるラッパーで、return_value と組み合わせて使います。

これで、関数の仕組みについて、それなりに理解できたことでしょう。 メソッドの仕組みについても、ある程度は理解できたはずです。


サイト内検索