|
|
@@ -7,7 +7,7 @@
|
|
|
Zend_Filter_Input provides a declarative interface to associate
|
|
|
multiple filters and validators, apply them to collections of data, and
|
|
|
to retrieve input values after they have been processed by the filters
|
|
|
- and validators. Values are returned in escaped format by default for
|
|
|
+ and validators. Values are returned in escaped format by default for
|
|
|
safe HTML output.
|
|
|
</para>
|
|
|
|
|
|
@@ -15,12 +15,12 @@
|
|
|
Consider the metaphor that this class is a cage for external data.
|
|
|
Data enter the application from external sources, such as HTTP request
|
|
|
parameters, HTTP headers, a web service, or even read from a database
|
|
|
- or another file. Data are first put into the cage, and subsequently
|
|
|
+ or another file. Data are first put into the cage, and subsequently
|
|
|
the application can access data only by telling the cage what the data
|
|
|
- should be and how they plan to use it. The cage inspects the data for
|
|
|
- validity. It might apply escaping to the data values for the
|
|
|
- appropriate context. The cage releases data only if it can fulfill
|
|
|
- these responsibilities. With a simple and convenient interface, it
|
|
|
+ should be and how they plan to use it. The cage inspects the data for
|
|
|
+ validity. It might apply escaping to the data values for the
|
|
|
+ appropriate context. The cage releases data only if it can fulfill
|
|
|
+ these responsibilities. With a simple and convenient interface, it
|
|
|
encourages good programming habits and makes developers think about how
|
|
|
data are used.
|
|
|
</para>
|
|
|
@@ -31,7 +31,7 @@
|
|
|
<emphasis role="strong">Filters</emphasis> transform input
|
|
|
values, by removing or changing characters within the value.
|
|
|
The goal is to "normalize" input values until they match an
|
|
|
- expected format. For example, if a string of numeric digits is
|
|
|
+ expected format. For example, if a string of numeric digits is
|
|
|
needed, and the input value is "abc123", then it might be a
|
|
|
reasonable transformation to change the value to the string
|
|
|
"123".
|
|
|
@@ -41,7 +41,7 @@
|
|
|
<para>
|
|
|
<emphasis role="strong">Validators</emphasis> check input
|
|
|
values against criteria and report whether they passed the test
|
|
|
- or not. The value is not changed, but the check may fail. For
|
|
|
+ or not. The value is not changed, but the check may fail. For
|
|
|
example, if a string must look like an email address, and the
|
|
|
input value is "abc123", then the value is not considered
|
|
|
valid.
|
|
|
@@ -50,12 +50,12 @@
|
|
|
<listitem>
|
|
|
<para>
|
|
|
<emphasis role="strong">Escapers</emphasis> transform a value
|
|
|
- by removing magic behavior of certain characters. In some
|
|
|
- output contexts, special characters have meaning. For example,
|
|
|
+ by removing magic behavior of certain characters. In some
|
|
|
+ output contexts, special characters have meaning. For example,
|
|
|
the characters '<' and '>' delimit HTML tags, and if a
|
|
|
string containing those characters is output in an HTML
|
|
|
context, the content between them might affect the output or
|
|
|
- functionality of the HTML presentation. Escaping the
|
|
|
+ functionality of the HTML presentation. Escaping the
|
|
|
characters removes the special meaning, so they are output as
|
|
|
literal characters.
|
|
|
</para>
|
|
|
@@ -107,7 +107,7 @@
|
|
|
<para>
|
|
|
The following example filter rule set that declares the field
|
|
|
'month' is filtered by Zend_Filter_Digits, and the field 'account'
|
|
|
- is filtered by Zend_Filter_StringTrim. Then a validation rule set
|
|
|
+ is filtered by Zend_Filter_StringTrim. Then a validation rule set
|
|
|
declares that the field 'account' is valid only if it contains only
|
|
|
alphabetical characters.
|
|
|
</para>
|
|
|
@@ -125,7 +125,7 @@ $validators = array(
|
|
|
|
|
|
<para>
|
|
|
Each key in the <code>$filters</code> array above is the name of a rule for applying a
|
|
|
- filter to a specific data field. By default, the name of the rule
|
|
|
+ filter to a specific data field. By default, the name of the rule
|
|
|
is also the name of the input data field to which to apply the
|
|
|
rule.
|
|
|
</para>
|
|
|
@@ -163,7 +163,7 @@ $validators = array(
|
|
|
An array, to declare a chain of filters or validators.
|
|
|
The elements of this array can be strings mapping to class
|
|
|
names or filter/validator objects, as in the cases
|
|
|
- described above. In addition, you can use a third choice:
|
|
|
+ described above. In addition, you can use a third choice:
|
|
|
an array containing a string mapping to the class name
|
|
|
followed by arguments to pass to its constructor.
|
|
|
|
|
|
@@ -190,9 +190,9 @@ $validators = array(
|
|
|
|
|
|
<para>
|
|
|
You can use a special "wildcard" rule key <code>'*'</code> in
|
|
|
- either the filters array or the validators array. This means that
|
|
|
+ either the filters array or the validators array. This means that
|
|
|
the filters or validators declared in this rule will be applied to
|
|
|
- all input data fields. Note that the order of entries in the
|
|
|
+ all input data fields. Note that the order of entries in the
|
|
|
filters array or validators array is significant; the rules are
|
|
|
applied in the same order in which you declare them.
|
|
|
</para>
|
|
|
@@ -212,7 +212,7 @@ $filters = array(
|
|
|
|
|
|
<para>
|
|
|
After declaring the filters and validators arrays, use them as
|
|
|
- arguments in the constructor of Zend_Filter_Input. This returns an
|
|
|
+ arguments in the constructor of Zend_Filter_Input. This returns an
|
|
|
object that knows all your filtering and validating rules, and you
|
|
|
can use this object to process one or more sets of input data.
|
|
|
</para>
|
|
|
@@ -222,11 +222,11 @@ $input = new Zend_Filter_Input($filters, $validators);
|
|
|
]]></programlisting>
|
|
|
|
|
|
<para>
|
|
|
- You can specify input data as the third constructor argument. The
|
|
|
- data structure is an associative array. The keys are field names,
|
|
|
- and the values are data values. The standard <code>$_GET</code>
|
|
|
+ You can specify input data as the third constructor argument. The
|
|
|
+ data structure is an associative array. The keys are field names,
|
|
|
+ and the values are data values. The standard <code>$_GET</code>
|
|
|
and <code>$_POST</code> superglobal variables in PHP are examples
|
|
|
- of this format. You can use either of these variables as input
|
|
|
+ of this format. You can use either of these variables as input
|
|
|
data for Zend_Filter_Input.
|
|
|
</para>
|
|
|
|
|
|
@@ -250,7 +250,7 @@ $input->setData($newData);
|
|
|
<para>
|
|
|
The <code>setData()</code> method redefines data in an existing
|
|
|
Zend_Filter_Input object without changing the filtering and
|
|
|
- validation rules. Using this method, you can run the same rules
|
|
|
+ validation rules. Using this method, you can run the same rules
|
|
|
against different sets of input data.
|
|
|
</para>
|
|
|
|
|
|
@@ -263,7 +263,7 @@ $input->setData($newData);
|
|
|
<para>
|
|
|
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
|
|
|
+ invalid fields. You also can get the values of fields after
|
|
|
filters have been applied.
|
|
|
</para>
|
|
|
|
|
|
@@ -286,7 +286,7 @@ if ($input->isValid()) {
|
|
|
|
|
|
<para>
|
|
|
This method accepts an optional string argument, naming
|
|
|
- an individual field. If the specified field passed validation
|
|
|
+ an individual field. If the specified field passed validation
|
|
|
and is ready for fetching, <code>isValid('fieldName')</code>
|
|
|
returns <code>true</code>.
|
|
|
</para>
|
|
|
@@ -354,7 +354,7 @@ if ($input->hasUnknown()) {
|
|
|
<para>
|
|
|
The results of the <code>getMessages()</code> 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
|
|
|
+ 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.
|
|
|
</para>
|
|
|
@@ -362,14 +362,14 @@ if ($input->hasUnknown()) {
|
|
|
<para>
|
|
|
The <code>getMessages()</code> method returns the merge of the
|
|
|
arrays returned by the <code>getInvalid()</code> and
|
|
|
- <code>getMissing()</code>. These methods return subsets of the
|
|
|
+ <code>getMissing()</code>. These methods return subsets of the
|
|
|
messages, related to validation failures, or fields that were
|
|
|
declared as required but missing from the input.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
The <code>getErrors()</code> method returns an associative array,
|
|
|
- mapping a rule name to an array of error identifiers. Error
|
|
|
+ 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 <xref linkend="zend.validate.introduction.using" /> for
|
|
|
@@ -398,7 +398,7 @@ $input->setOptions($options);
|
|
|
|
|
|
<para>
|
|
|
The results of the <code>getUnknown()</code> method is an
|
|
|
- associative array, mapping field names to field values. Field
|
|
|
+ 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.
|
|
|
@@ -412,8 +412,8 @@ $input->setOptions($options);
|
|
|
|
|
|
<para>
|
|
|
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
|
|
|
+ considered valid. You can get values for valid fields using a
|
|
|
+ magic accessor. There are also non-magic accessor methods
|
|
|
<code>getEscaped()</code> and <code>getUnescaped()</code>.
|
|
|
</para>
|
|
|
|
|
|
@@ -425,9 +425,9 @@ $m = $input->getUnescaped('month'); // not escaped
|
|
|
|
|
|
<para>
|
|
|
By default, when retrieving a value, it is filtered with the
|
|
|
- Zend_Filter_HtmlEntities. This is the default because it is
|
|
|
+ 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
|
|
|
+ in HTML. The HtmlEntities filter helps prevent unintentional
|
|
|
output of code, which can result in security problems.
|
|
|
</para>
|
|
|
|
|
|
@@ -463,18 +463,18 @@ $input->setDefaultEscapeFilter(new Zend_Filter_StringTrim());
|
|
|
<para>
|
|
|
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
|
|
|
+ filter class. The escape filter can be an instance of a filter
|
|
|
chain, an object of the class Zend_Filter.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
Filters to escape output should be run in this way, to make
|
|
|
- sure they run after validation. Other filters you declare in
|
|
|
+ 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,
|
|
|
+ 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
|
|
|
+ data. So it is recommended to declare filters to escape output
|
|
|
using <code>setDefaultEscapeFilter()</code>, not in the
|
|
|
<code>$filters</code> array.
|
|
|
</para>
|
|
|
@@ -482,7 +482,7 @@ $input->setDefaultEscapeFilter(new Zend_Filter_StringTrim());
|
|
|
<para>
|
|
|
There is only one method <code>getEscaped()</code>, and
|
|
|
therefore you can specify only one filter for escaping
|
|
|
- (although this filter can be a filter chain). If you need a
|
|
|
+ (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
|
|
|
@@ -501,7 +501,7 @@ $input->setDefaultEscapeFilter(new Zend_Filter_StringTrim());
|
|
|
In addition to declaring the mapping from fields to filters
|
|
|
or validators, you can specify some "metacommands" in the array
|
|
|
declarations, to control some optional behavior of
|
|
|
- Zend_Filter_Input. Metacommands appear as string-indexed
|
|
|
+ Zend_Filter_Input. Metacommands appear as string-indexed
|
|
|
entries in a given filter or validator array value.
|
|
|
</para>
|
|
|
|
|
|
@@ -532,7 +532,7 @@ $filters = array(
|
|
|
|
|
|
<para>
|
|
|
In the example above, the filter rule applies the 'digits'
|
|
|
- filter to the input field named 'mo'. The string 'month'
|
|
|
+ filter to the input field named 'mo'. The string 'month'
|
|
|
simply becomes a mnemonic key for this filtering rule; it is
|
|
|
not used as the field name if the field is specified with the
|
|
|
'fields' metacommand, but it is used as the rule name.
|
|
|
@@ -540,7 +540,7 @@ $filters = array(
|
|
|
|
|
|
<para>
|
|
|
The default value of the 'fields' metacommand is the index of
|
|
|
- the current rule. In the example above, if the 'fields'
|
|
|
+ the current rule. In the example above, if the 'fields'
|
|
|
metacommand is not specified, the rule would apply to the input
|
|
|
field named 'month'.
|
|
|
</para>
|
|
|
@@ -548,11 +548,11 @@ $filters = array(
|
|
|
<para>
|
|
|
Another use of the 'fields' metacommand is to specify fields
|
|
|
for filters or validators that require multiple fields as
|
|
|
- input. If the 'fields' metacommand is an array, the argument
|
|
|
+ input. If the 'fields' metacommand is an array, the argument
|
|
|
to the corresponding filter or validator is an array of the
|
|
|
- values of those fields. For example, it is common for users to
|
|
|
+ values of those fields. For example, it is common for users to
|
|
|
specify a password string in two fields, and they must type the
|
|
|
- same string in both fields. Suppose you implement a validator
|
|
|
+ same string in both fields. Suppose you implement a validator
|
|
|
class that takes an array argument, and returns
|
|
|
<code>true</code> if all the values in the array are equal to
|
|
|
each other.
|
|
|
@@ -585,7 +585,7 @@ $validators = array(
|
|
|
|
|
|
<para>
|
|
|
Each entry in the validator array may have a metacommand called
|
|
|
- 'presence'. If the value of this metacommand is 'required'
|
|
|
+ 'presence'. If the value of this metacommand is 'required'
|
|
|
then the field must exist in the input data, or else it is
|
|
|
reported as a missing field.
|
|
|
</para>
|
|
|
@@ -629,10 +629,10 @@ $validators = array(
|
|
|
|
|
|
<para>
|
|
|
This default value is assigned to the field before any of the
|
|
|
- validators are invoked. The default value is applied to the
|
|
|
+ validators are invoked. The default value is applied to the
|
|
|
field only for the current rule; if the same field is
|
|
|
referenced in a subsequent rule, the field has no value when
|
|
|
- evaluating that rule. Thus different rules can declare
|
|
|
+ evaluating that rule. Thus different rules can declare
|
|
|
different default values for a given field.
|
|
|
</para>
|
|
|
|
|
|
@@ -656,7 +656,7 @@ echo $input->month; // echoes 1
|
|
|
to define an array of multiple fields, you can define
|
|
|
an array for the <code>DEFAULT_VALUE</code> metacommand
|
|
|
and the defaults of corresponding keys are used for any
|
|
|
- missing fields. If <code>FIELDS</code> defines multiple
|
|
|
+ missing fields. If <code>FIELDS</code> defines multiple
|
|
|
fields but <code>DEFAULT_VALUE</code> is a scalar, then
|
|
|
that default value is used as the value for any missing
|
|
|
fields in the array.
|
|
|
@@ -675,8 +675,8 @@ echo $input->month; // echoes 1
|
|
|
<para>
|
|
|
By default, if a field exists in the input data, then
|
|
|
validators are applied to it, even if the value of the field is
|
|
|
- an empty string (<code>''</code>). This is likely to result in
|
|
|
- a failure to validate. For example, if the validator checks
|
|
|
+ an empty string (<code>''</code>). This is likely to result in
|
|
|
+ a failure to validate. For example, if the validator checks
|
|
|
for digit characters, and there are none because a zero-length
|
|
|
string has no characters, then the validator reports the data
|
|
|
as invalid.
|
|
|
@@ -713,7 +713,7 @@ $validators = array(
|
|
|
no validators, but the 'allowEmpty' metacommand is
|
|
|
<code>false</code> (that is, the field is considered invalid if
|
|
|
it is empty), Zend_Filter_Input returns a default error message
|
|
|
- that you can retrieve with <code>getMessages()</code>. You can
|
|
|
+ that you can retrieve with <code>getMessages()</code>. You can
|
|
|
specify this message using the 'notEmptyMessage' option, as an
|
|
|
argument to the Zend_Filter_Input constructor or using the
|
|
|
<code>setOptions()</code> method.
|
|
|
@@ -747,7 +747,7 @@ $input->setOptions($options);
|
|
|
<para>
|
|
|
Alternatively, if the value of the 'breakChainOnFailure'
|
|
|
metacommand is <code>true</code>, the validator chain
|
|
|
- terminates after the first validator fails. The input data is
|
|
|
+ terminates after the first validator fails. The input data is
|
|
|
not checked against subsequent validators in the chain, so it
|
|
|
might cause more violations even if you correct the one
|
|
|
reported.
|
|
|
@@ -782,7 +782,7 @@ $input = new Zend_Filter_Input(null, $validators);
|
|
|
chain on failure independently for each validator in the chain.
|
|
|
With the latter class, the defined value of the
|
|
|
'breakChainOnFailure' metacommand for a rule applies uniformly
|
|
|
- for all validators in the rule. If you require the more
|
|
|
+ for all validators in the rule. If you require the more
|
|
|
flexible usage, you should create the validator chain yourself,
|
|
|
and use it as an object in the validator rule
|
|
|
definition:
|
|
|
@@ -811,7 +811,7 @@ $input = new Zend_Filter_Input(null, $validators);
|
|
|
|
|
|
<para>
|
|
|
You can specify error messages for each validator in a rule
|
|
|
- using the metacommand 'messages'. The value of this metacommand
|
|
|
+ using the metacommand 'messages'. The value of this metacommand
|
|
|
varies based on whether you have multiple validators in the
|
|
|
rule, or if you want to set the message for a specific error
|
|
|
condition in a given validator.
|
|
|
@@ -845,9 +845,9 @@ $validators = array(
|
|
|
|
|
|
<para>
|
|
|
Each element of this array is applied to the validator at the
|
|
|
- same index position. You can specify a message for the
|
|
|
+ same index position. You can specify a message for the
|
|
|
validator at position <emphasis>n</emphasis> by using the value
|
|
|
- <emphasis>n</emphasis> as the array index. Thus you can allow
|
|
|
+ <emphasis>n</emphasis> as the array index. Thus you can allow
|
|
|
some validators to use their default message, while setting the
|
|
|
message for a subsequent validator in the chain.
|
|
|
</para>
|
|
|
@@ -868,10 +868,10 @@ $validators = array(
|
|
|
|
|
|
<para>
|
|
|
If one of your validators has multiple error messages, they are
|
|
|
- identified by a message key. There are different keys in each
|
|
|
+ identified by a message key. There are different keys in each
|
|
|
validator class, serving as identifiers for error messages that
|
|
|
- the respective validator class might generate. Each validate
|
|
|
- class defines constants for its message keys. You can use
|
|
|
+ the respective validator class might generate. Each validate
|
|
|
+ class defines constants for its message keys. You can use
|
|
|
these keys in the 'messages' metacommand by passing an
|
|
|
associative array instead of a string.
|
|
|
</para>
|
|
|
@@ -911,7 +911,7 @@ $validators = array(
|
|
|
The default value for 'allowEmpty', 'breakChainOnFailure', and
|
|
|
'presence' metacommands can be set for all rules using the
|
|
|
<code>$options</code> argument to the constructor of
|
|
|
- Zend_Filter_Input. This allows you to set the default value
|
|
|
+ Zend_Filter_Input. This allows you to set the default value
|
|
|
for all rules, without requiring you to set the metacommand for
|
|
|
every rule.
|
|
|
</para>
|
|
|
@@ -948,7 +948,7 @@ $input = new Zend_Filter_Input($filters, $validators, $data, $options);
|
|
|
<para>
|
|
|
By default, when you declare a filter or validator as a string,
|
|
|
Zend_Filter_Input searches for the corresponding classes under
|
|
|
- the Zend_Filter or Zend_Validate namespaces. For example,
|
|
|
+ the Zend_Filter or Zend_Validate namespaces. For example,
|
|
|
a filter named by the string 'digits' is found in the class
|
|
|
Zend_Filter_Digits.
|
|
|
</para>
|
|
|
@@ -956,8 +956,8 @@ $input = new Zend_Filter_Input($filters, $validators, $data, $options);
|
|
|
<para>
|
|
|
If you write your own filter or validator classes, or use filters
|
|
|
or validators provided by a third-party, the classes may exist in
|
|
|
- different namespaces than Zend_Filter or Zend_Validate. You can
|
|
|
- tell Zend_Filter_Input to search more namespaces. You can specify
|
|
|
+ different namespaces than Zend_Filter or Zend_Validate. You can
|
|
|
+ tell Zend_Filter_Input to search more namespaces. You can specify
|
|
|
namespaces in the constructor options:
|
|
|
</para>
|
|
|
|
|
|
@@ -990,7 +990,7 @@ $input->addFilterPrefixPath('Foo_Namespace', 'Foo/Namespace');
|
|
|
|
|
|
<para>
|
|
|
You cannot remove Zend_Filter and Zend_Validate as namespaces, you
|
|
|
- only can add namespaces. User-defined namespaces are searched
|
|
|
+ only can add namespaces. User-defined namespaces are searched
|
|
|
first, Zend namespaces are searched last.
|
|
|
</para>
|
|
|
|