16.5. Zend_Filter_Input

如果所有输入数据通过校验，isValid() 方法返回 true。 如果有任何字段无效或者任何要求的字段不存在，则返回 false。

<?php
if ($input->isValid()) {
  echo "OK\n";
}
            

该方法接受一个可选的字符串参数，即一个独立字段。如果指定的字段 通过校验并为读取准备好，isValid('fieldName') 返回 true。

<?php
if ($input->isValid('month')) {
  echo "Field 'month' is OK\n";
}
            

<?php
if ($input->hasInvalid() || $input->hasMissing()) {
  $messages = $input->getMessages();
}

// getMessages() simply returns the merge of getInvalid() and getMissing()

if ($input->hasInvalid()) {
  $invalidFields = $input->getInvalid();
}

if ($input->hasMissing()) {
  $missingFields = $input->getMissing();
}

if ($input->hasUnknown()) {
  $unknownFields = $input->getUnknown();
}
            

getMessages() 方法的结果是一个关联数组，映射规则名到一个和该规则相关的错误消息的数组。 注意该数组的索引是用在规则声明的规则名，它可能和由该规则检查的字段名不同。

getMessages() 方法返回由 getInvalid() 和 getMissing() 的返回的数组的合并。 这些方法返回消息的子集，和校验失败相关，或者必需声明的字段没有输入。

The getErrors() 方法返回一个关联数组，映射规则名到错误识别器的数组。 错误识别器是规定字符串，用来识别校验错误的原因，消息可以定制。 参见 第 44.1.2 节 “校验器的基本用法” 有更多信息。

你可以指定使用 'missingMessage' 选项的 getMissing() 返回的消息作为 Zend_Filter_Input 构造器的参数或者使用 setOptions() 方法。

<?php
$options = array(
    'missingMessage' => "Field '%field%' is required"
);

$input = new Zend_Filter_Input($filters, $validators, $data, $options);

// alternative method:

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setOptions($options);
            

getUnknown() 方法的结果是一个关联数组，映射字段名到字段值。 在这个例子中，字段名（而不是规则名）用作数组键，因为不涉及规则的字段被当作未知字段。

所有不是无效的、丢失的、未知的字段都是有效的（好像废话一样 Jason Qi）。 你可以用魔术访问器来获得有效字段的值。也有非魔术访问器方法 getEscaped() 和 getUnescaped()。

<?php
$m = $input->month;                 // escaped output from magic accessor
$m = $input->getEscaped('month');   // escaped output
$m = $input->getUnescaped('month'); // not escaped
            

缺省地，当读取一个值时，用 Zend_Filter_HtmlEntities 来过滤。 因为它是在 HTML 中输出字段值的最普通的用法，所以它是缺省的。 HtmlEntities 过滤器有助于防止无意识的、可能会导致安全问题的代码输出。

	注意
	正如上所述，你可以使用 getUnescaped() 方法读取非转义的值， 但必需安全地使用这些值，避免安全问题如被跨站脚本攻击的弱点。

你可以通过在构造器选项数组里指定转义值来为它指定一个不同的过滤器：

<?php
$options = array('escapeFilter' => 'StringTrim');
$input = new Zend_Filter_Input($filters, $validators, $data, $options);
            

另外，你也可以使用 setDefaultEscapeFilter() 方法：

<?php
$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setDefaultEscapeFilter(new Zend_Filter_StringTrim());
            

对于任何一种用法，你可以指定转义过滤器作为过滤器类的字符串基础名 或者过滤器类的对象实例。转义过滤器可以是过滤器链的实例、Zend_Filter 类的对象。

转义输出的过滤器应当确保在校验之后运行，其它在过滤器规则的数组中声明的过滤器在数据校验之前应用。 如果转义过滤器在校验之前运行，校验的处理将会很复杂，也将很难提供转义的和非转义的数据版本。 建议使用 setDefaultEscapeFilter() 来声明转义输出的过滤器，而不是在 $filters 数组中。

只有一个方法 getEscaped()，所以你只可以为转义（尽管这个过滤器可以是个过滤器链）指定一个过滤器。 如果需要一个单个的 Zend_Filter_Input 实例来返回使用超过一个过滤器方法的转义输出，你应该继承 Zend_Filter_Input 并在你的子类里实现新方法来用不同的方法获取数值。

如果过滤器或校验器的规则名和需要应用规则的字段名不同，可以用 'fields' metacommand 来指定字段名。

可以用类常量 Zend_Filter_Input::FIELDS 而不是字符串来指定这个 metacommand。

<?php
$filters = array(
    'month' => array(
        'Digits',        // filter name at integer index [0]
        'fields' => 'mo' // field name at string index ['fields']
    )
);
            

在上例中，过滤器规则使用 'digits' 过滤器给名为 'mo' 的输入字段。 字符串 'month' 变成这个过滤规则的助记键，如果用 'fields' metacommand 指定字段，它不能用做字段名，但可用作规则名。

'fields' metacommand 的缺省值是当前规则的索引。在上例中，如果 'fields' metacommand 没有被指定，规则就应用于名为 'month' 的输入字段。

'fields' metacommand 的另一个使用是为过滤器或校验器指定字段，这里过滤器或校验器要求多个字段作为输入。 如果 'fields' metacommand 是个数组，过滤器或校验器相应的参数是一个那些字段值的数组。 例如，通常用户会在两个字段中指定密码字符串，他们必需在两个字段中输入相同的字符串。 假定你实现一个校验器类，带有一个数组参数，如果数组中所有的值彼此相等，就返回 true。

<?php
$validators = array(
    'password' => array(
        'StringEquals',
        'fields' => array('password1', 'password2')
    )
);
// Invokes hypothetical class Zend_Validate_StringEquals, passing an array argument
// containing the values of the two input data fields named 'password1' and 'password2'.
            

如果这个规则校验失败，规则键（'password'）用于 getInvalid() 的返回值，不是命名在 'fields' metacommand 中的其它字段。

在校验器数组里的每个条目可能有一个叫做 'presence' 的 metacommand。 如果这个 metacommand 的值是 'required'，那么字段必需存在于输入数据， 否则，就报告为丢失字段。

你可以用类常量 Zend_Filter_Input::PRESENCE 而不是字符串来指定这个 metacommand。

<?php
$validators = array(
    'month' => array(
        'digits',
        'presence' => 'required'
    )
);
            

这个 metacommand 的缺省值是 'optional'。

如果字段没有出现在输入数据里，并且你为了规则为 'default' metacommand 指定一个值， 这个字段就用 metacommand 的值。

你可以用类常量 Zend_Filter_Input::DEFAULT_VALUE 而不是字符串来指定这个 metacommand。

在任何校验器被调用之前，这个缺省值被分配给字段。缺省值只为当前规则应用于字段， 如果同样的字段在后来的规则被引用，当评估规则时字段没有值。 这样，对于给定的字段不同的规则可以声明不同的缺省值。

<?php
$validators = array(
    'month' => array(
        'digits',
        'default' => '1'
    )
);

// no value for 'month' field
$data = array();

$input = new Zend_Filter_Input(null, $validators, $data);
echo $input->month; // echoes 1
            

如果你的规则使用 FIELDS metacommand 来定义多重字段的数组， 你可以为 DEFAULT_VALUE metacommand 定义一个数组并且相应键的缺省用于任何丢失的字段。 如果 FIELDS 定义多重字段但 DEFAULT_VALUE 是个标量，那么 缺省值用于任何在数组中的丢失的字段。

这个 metacommand 没有缺省值。

缺省地，如果一个字段存在于输入数据，那么校验器就应用其上，即使字段值是空的（''）。 这可能导致一个校验失败，例如：如果校验器检查数字字符，并且因为零长度字符串是没有字符，那么校验器就报告数据错误。

如果读你来说空字符应当认为有效，你可以设置 metacommand 'allowEmpty' 为 true。 这样空字符的输入数据就可以通过校验。

你可以用类常量 Zend_Filter_Input::ALLOW_EMPTY 而不是字符串来指定这个 metacommand。

<?php
$validators = array(
    'address2' => array(
        'Alnum',
        'allowEmpty' => true
    )
);
            

这个 metacommand 的缺省值是 false。

在非正常情况下你声明没有校验器的校验规则，但 'allowEmpty' metacommand 是 false （即如果字段是空的就被认为无效）， Zend_Filter_Input 返回缺省错误消息，你可以用 getMessages() 来读取。 你可以用 'notEmptyMessage' 选项作为 Zend_Filter_Input 构造器的参数或使用 setOptions() 方法来指定这个消息。

<?php
$options = array(
    'notEmptyMessage' => "A non-empty value is required for field '%field%'"
);

$input = new Zend_Filter_Input($filters, $validators, $data, $options);

// alternative method:

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setOptions($options);
            

缺省地，如果一个规则有多于一个校验器，所有校验器应用于输入，并且返回的消息包含所有由输入导致的错误消息。

另外，如果 'breakChainOnFailure' metacommand 的值是 true， 校验器链在第一次校验失败时就终止，输入数据不再被链中的后来的校验器检查， 即使你纠正被报告的那一个，也很可能导致更多的冲突。

你可以用类常量 Zend_Filter_Input::BREAK_CHAIN 而不是字符串来指定这个 metacommand。

<?php
$validators = array(
    'month' => array(
        'Digits',
        new Zend_Validate_Between(1,12),
        new Zend_Validate_GreaterThan(0),
        'breakChainOnFailure' => true
    )
);
$input = new Zend_Filter_Input(null, $validators);
            

这个 metacommand 的缺省值是 false。

校验器链类 Zend_Validate 在中断链执行方面比 Zend_Filter_Input 更灵活。 对于前者，你可以设置选项来对链中每个校验器独立地根据失败来中断链。 对于后者，'breakChainOnFailure' metacommand 的定义值对规则来说一律适用所有规则中的校验器。 如果你需要更灵活的用法，要创建自己的校验器链，在校验器规则定义里把它用作一个对象：

<?php
// Create validator chain with non-uniform breakChainOnFailure attributes
$chain = new Zend_Validate();
$chain->addValidator(new Zend_Validate_Digits(), true);
$chain->addValidator(new Zend_Validate_Between(1,12), false);
$chain->addValidator(new Zend_Validate_GreaterThan(0), true);

// Declare validator rule using the chain defined above
$validators = array(
    'month' => $chain
);
$input = new Zend_Filter_Input(null, $validators);
            

你可以使用 metacommand 'messages' 为在规则中的每个校验器指定错误消息。 这个 metacommand 的值在规则中根据你是否有多重校验器而不同， 或者如果你想在给定的校验器中为特定错误条件设置消息。

你可以用类常量 Zend_Filter_Input::MESSAGES 而不是字符串来指定这个 metacommand。

下面是为单个校验器设置缺省错误消息的例子。

<?php
$validators = array(
    'month' => array(
        'digits',
        'messages' => 'A month must consist only of digits'
    )
);
            

如果你想给多重校验器设置错误消息，对 'messages' metacommand 的值应当使用一个数组。

这个数组的每个元素应用于在同一索引位置的校验器。你可以通过把值 n 作为数组索引为在 n 位置的校验器指定消息。 这样当在链中为后来的校验器设置消息，一些校验器就使用它们自己的缺省消息。

<?php
$validators = array(
    'month' => array(
        'digits',
        new Zend_Validate_Between(1, 12),
        'messages' => array(
            // use default message for validator [0]
            // set new message for validator [1]
            1 => 'A month value must be between 1 and 12'
        )
    )
);
            

如果你的校验器其中一个有多重错误消息，它们由消息键来识别。 在每个校验器类里有不同的键，作为识别器服务于各自校验器类可能产生的错误消息。 每个校验类为它的消息键定义常量。你可以通过传递关联数组而不是字符串来在 'messages' metacommand 里使用这些键。

<?php
$validators = array(
    'month' => array(
        'digits', new Zend_Validate_Between(1, 12),
        'messages' => array(
            'A month must consist only of digits',
            array(
                Zend_Validate_Between::NOT_BETWEEN =>
                    'Month value %value% must be between %min% and %max%',
                Zend_Validate_Between::NOT_BETWEEN_STRICT =>
                    'Month value %value% must be strictly between %min% and %max%'
            )
        )
    )
);
            

你应当参考每个校验器类的文档来获知它是否有多重错误消息、这些消息的键和可用于消息模板的令牌。

'allowEmpty'、 'breakChainOnFailure' 和 'presence' metacommands 的缺省值可以使用 Zend_Filter_Input 构造器的 $options 参数来为所有的规则设置。 它让你为所有的规则设置缺省值而不需要为每个规则设置 metacommand。

<?php
// The default is set so all fields allow an empty string.
$options = array('allowEmpty' => true);

// You can override this in a rule definition,
// if a field should not accept an empty string.
$validators = array(
    'month' => array(
        'Digits',
        'allowEmpty' => false
    )
);

$input = new Zend_Filter_Input($filters, $validators, $data, $options);
            

'fields'、'messages' 和 'default' metacommands 不能用这个技术来设置。