PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

Retrieving Validated Fields and other Reports

After you have declared filters and validators and created the input processor, you can retrieve reports of missing, unknown, and invalid fields. You also can get the values of fields after filters have been applied.

Querying if the input is valid

If all input data pass the validation rules, the isValid() method returns TRUE. If any field is invalid or any required field is missing, isValid() returns FALSE.

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

This method accepts an optional string argument, naming an individual field. If the specified field passed validation and is ready for fetching, isValid('fieldName') returns TRUE.

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

Getting Invalid, Missing, or Unknown Fields

  • Invalid fields are those that don't pass one or more of their validation checks.

  • Missing fields are those that are not present in the input data, but were declared with the metacommand 'presence'=>'required' (see the later section on metacommands).

  • Unknown fields are those that are not declared in any rule in the array of validators, but appear in the input data.

<?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();
}

The results of the getMessages() method is an associative array, mapping a rule name to an array of error messages related to that rule. Note that the index of this array is the rule name used in the rule declaration, which may be different from the names of fields checked by the rule.

The getMessages() method returns the merge of the arrays returned by the getInvalid() and getMissing(). These methods return subsets of the messages, related to validation failures, or fields that were declared as required but missing from the input.

The getErrors() method returns an associative array, mapping a rule name to an array of error identifiers. Error identifiers are fixed strings, to identify the reason for a validation failure, while messages can be customized. See this chapter for more information.

You can specify the message returned by getMissing() using the 'missingMessage' option, as an argument to the Zend_Filter_Input constructor or using the setOptions() method.

<?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);

And you can also add a translator which gives you the ability to provide multiple languages for the messages which are returned by Zend_Filter_Input.

<?php
$translate 
= new Zend_Translate_Adapter_Array(array(
    
'content' => array(
        
Zend_Filter_Input::MISSING_MESSAGE => "Where is the field?"
    
)
);

$input = new Zend_Filter_Input($filters$validators$data);
$input->setTranslator($translate);

When you are using an application wide translator, then it will also be used by Zend_Filter_Input. In this case you will not have to set the translator manually.

The results of the getUnknown() method is an associative array, mapping field names to field values. Field names are used as the array keys in this case, instead of rule names, because no rule mentions the fields considered to be unknown fields.

Getting Valid Fields

All fields that are neither invalid, missing, nor unknown are considered valid. You can get values for valid fields using a magic accessor. There are also non-magic accessor methods getEscaped() and getUnescaped().

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

By default, when retrieving a value, it is filtered with the Zend_Filter_HtmlEntities. This is the default because it is considered the most common usage to output the value of a field in HTML. The HtmlEntities filter helps prevent unintentional output of code, which can result in security problems.

Note

As shown above, you can retrieve the unescaped value using the getUnescaped() method, but you must write code to use the value safely, and avoid security issues such as vulnerability to cross-site scripting attacks.

Escaping unvalidated fields

As mentioned before getEscaped() returns only validated fields. Fields which do not have an associated validator can not be received this way. Still, there is a possible way. You can add a empty validator for all fields.

<?php
$validators 
= array('*' => array());

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

But be warned that using this notation introduces a security leak which could be used for cross-site scripting attacks. Therefor you should always set individual validators for each field.

You can specify a different filter for escaping values, by specifying it in the constructor options array:

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

Alternatively, you can use the setDefaultEscapeFilter() method:

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

In either usage, you can specify the escape filter as a string base name of the filter class, or as an object instance of a filter class. The escape filter can be an instance of a filter chain, an object of the class Zend_Filter.

Filters to escape output should be run in this way, to make sure they run after validation. Other filters you declare in the array of filter rules are applied to input data before data are validated. If escaping filters were run before validation, the process of validation would be more complex, and it would be harder to provide both escaped and unescaped versions of the data. So it is recommended to declare filters to escape output using setDefaultEscapeFilter(), not in the $filters array.

There is only one method getEscaped(), and therefore you can specify only one filter for escaping (although this filter can be a filter chain). If you need a single instance of Zend_Filter_Input to return escaped output using more than one filtering method, you should extend Zend_Filter_Input and implement new methods in your subclass to get values in different ways.

Zend Framework