コンバート関数とバリデート関数

バリデートやコンバート(変換)の処理を行う際、どのような関数を用いてどのように引数を与えて処理するのかというルールを配列で指定します。この配列をフィルタ配列(filter array)といいます。

たとえばフォームのコンストラクタでバリデーションを定義する場合

$this->set(
	'phone01' => array(
		'type'		=> 'text',
		'option'	=> 'size="11"',
		'validate'	=> $filter_array,
	)
);

モデルのコンストラクタでフォーマット(表示形式)を定義する場合

$this->setFormats(
	array(
		'birth_date' => array( 
			'convert' => $filter_array,
		)
	)
);

における$filter_arrayです。
バリデートでもコンバートでもそれらを行う際、一連の処理が発生します。その処理をフィルタ配列として指定するのです。

フィルタ配列

フィルタ配列では

を指定します。

$filter_array = array(
	'func'		=> 'cz_min_char',
	'params'	=> array('n' => 3, 'x' => array('ref' => 'number')),
	'err_msg'	=> 'だめです。',
);

要素は以下のとおりです。

func (string / array) (required)
処理を行う関数とそれに与える引数を指定します。 Chimpanzee備え付けのコンバート/バリデート関数に加えてPHPネイティブの関数や自作のクラスメソッド(関数)が使用できます。
Chimpanzee備え付けの関数やPHPネイティブの関数を使用する場合、関数名を文字列で指定します。
'func' => 'cz_date_parts',
自作の関数(作成方法は関数を自作する場合を参照)を使用する場合、クラス名とメソッド名の対を配列で指定します。
'func' => array('Class_name', 'method_name'),
params (assoc array) (option)
funcの関数の引数を連想配列で指定します。形式は、キーが関数の引数名、値が引数に代入する値となります。
'params' => array(
	'year'	=> 2011,
	'month'	=> array('ref' => 'month'),
	'day'	=> array('ref' => 'day'),
)
フィルタ用の関数(コンバート/バリデート関数)は引数を連想配列で与えます(詳細はフィルタ関数を参照)が、その連想配列のキーがここで指定する連想配列のキーとなります。
たとえばバリデート関数cz_date_parts($params)
$params = array(
	'year'	=> integer,
	'month'	=> integer,
	'day'	=> integer,
);
という引数をとりますが、この配列の要素であるyearmonthdayに値を渡す場合、
$filter_array = array(
	'func'		=> 'cz_date_parts',
	'params'	=> array(
		'year'	=> 2011,
		'month'	=> array('ref' => 'month'),
		'day'	=> array('ref' => 'day'),
	)
)
となります。
代入する値のほうですが、 固定値を与えるのであれば上記のyearのように定数で与えます。
フォームの入力タグやカラムの値(変数)を取得してきて代入する場合は
array('ref' => 'カラム名')
array('ref' => 'インプット名')
のようにキーをref、値を変数名とする特殊な連想配列を指定します。
err_msg (string) (option)
バリデートのみ指定する要素で、エラーメッセージを指定します。指定しない場合、Chimpanzeeデフォルトのバリデーションエラーメッセージが出力されます。

上記のようなフィルタ配列そのものを複数並べた配列を指定することで、パイプのように複数のメソッドによる処理を連結することも可能です。

$filter_array = array(
	array(
		'func'		=> 'cz_min_char',
		'params'	=> array('n' => 3, 'x' => array('ref' => 'number')),
		'err_msg'	=> 'だめです。',
	),
	array(
		'func'		=> 'cz_max_char',
		'params'	=> array('n' => 10, 'x' => array('ref' => 'number')),
		'err_msg'	=> 'だめですよ。',
	),
	array(
		'func'		=> array('Class', 'method'),
		'params'	=> array('x' => array('ref' => 'number'), 'y' => 1000),
		'err_msg'	=> 'いけません。',
	),
		:
);

フィルタ関数

バリデートやコンバートを行う関数は引数として1個の連想配列をとります。その要素としてバリデート関数ではバリデート対象とする文字列を、コンバート関数ではコンバート元となる文字列を指定します。

引数の値が1個の場合、要素が1個の連想配列となります。たとえば引数として1個の文字列をとるバリデート関数cz_date($params)では

$params = array('subject' => $subject);

引数として複数の値をとる場合、たとえば年月日の3個の値から日付データに変換するコンバート関数cz_date_join($params)では

$params = array(
	'year'	=> $year,
	'month'	=> $month,
	'day'	=> $day,
);

となります。関数内では$params['year']$params['month']などと$paramsのキーで識別して各処理を行います。

バリデートやコンバートを行う対象自身(バリデートであればここでバリデーションルールを定義しているフォームの入力タグ、コンバートであれば変換ルールを定義しているカラム)の値は連想配列のキーsubjectの値すなわち$params['subject']で取得できます。

通常フィルタ関数の引数に値を代入する場合はフィルタ配列のparamsarray('ref' => ... )の形式で指定しますが、対象自身の値を取得する場合はそれを使わなくても関数内で$params['subject']から取得できるのです。

多くのフィルタ関数では引数として対象自身の値($params['subject'])のみをとればいいので、その場合フィルタ配列のparamsを省略してfuncの指定のみでフィルタを定義することができます。

$filter_array = array('func' => 'cz_jpmobile_tel_num');
$filter_array = array('func' => 'cz_jp_zip_code');

関数を自作する

バリデートやコンバートを行う関数には以下の実装済みのものもあれば、関数を自作することもできます。自作する場合は関数を外部ライブラリもしくはフレームワークの拡張機能として実装します。

バリデート関数
値(subject)が有効な場合から文字「''」を、無効な場合エラーメッセージを文字列で返します。
コンバート関数
変換済みの値を文字列で返します。

実装済み関数の場合はフィルタ配列のfuncで関数名を、自作した関数を使用する場合はフィルタ配列のfuncでクラス名とメソッド名の対を配列で指定します。

'func' => array('Class_name', 'method_name'),

前後のページ

ページトップへ