Zeta Components - high quality PHP components

This class allows you to retrieve input variables from the request in a safe way, by applying filters to allow only wanted data into your application. It works by passing an array that describes your form definition to the constructor of the class. The constructor will then initialize the class with properties that contain the value of your request's input fields.

Example:

1.  <?php
2.  if ( ezcInputForm::hasGetData() )
3.  {
4.      $definition = array(
5.         'fieldname'  => new ezcInputFormDefinitionElement(
6.                             ezcInputFormDefinitionElement::REQUIRED, 'filtername'
7.                         ),
8.         'textfield'  => new ezcInputFormDefinitionElement(
9.                             ezcInputFormDefinitionElement::OPTIONAL, 'string'
10.                         ),
11.         'integer1'   => new ezcInputFormDefinitionElement(
12.                             ezcInputFormDefinitionElement::REQUIRED, 'int',
13.                             array( 'min_range' => 0, 'max_range' => 42 )
14.                         ),
15.         'xmlfield'   => new ezcInputFormDefinitionElement(
16.                             ezcInputFormDefinitionElement::REQUIRED, 'unsafe_raw'
17.                         ),
18.         'special'    => new ezcInputFormDefinitionElement(
19.                             ezcInputFormDefinitionElement::OPTIONAL, 'callback',
20.                             array( 'ezcInputFilter', 'special' )
21.                         ),
22.      );
23.      $form = new ezcInputForm( INPUT_GET, $definition );
24.      if ( $form->hasInputField( 'textfield' ) ) // check for optional field
25.      {
26.          $text = $form->textfield;
27.      }
28.  
29.      try
30.      {
31.          $xml = $form->xmlfield; // Uses dynamic properties through __get().
32.          $field = $form->fieldname;
33.          $int = $form->integer1;
34.      }
35.      catch ( ezcInputFormException $e )
36.      {
37.          // one of the required fields didn't have valid data.
38.          $invalidProperties = $form->getInvalidProperties();
39.  
40.          // Retrieve RAW data for invalid properties so that we can fill in the
41.          // forms online with this RAW data again - Make sure to escape it on
42.          // output though, but that should be done for all data anyway.
43.          if ( in_array( 'xmlfield', $invalidProperties ) )
44.          {
45.              $xml = $form->getUnsafeRawData( 'xmlfield' );
46.          }
47.      }
48.  
49.      // Checking optional fields
50.      foreach ( $form->getOptionalProperties() as $property )
51.      {
52.          $name = "property_{$property}";
53.          if ( $form->hasValidData( $property ) )
54.          {
55.              $$name = $form->$property;
56.          }
57.      }
58.  }
59.  ?>

Before reading the values from the input source, the definition array can be validated by this method to check whether all necessary elements are correctly formed.

With the following code you can check whether the definition is valid:

1.  <?php
2.  if ( ( $returnValue = ezcInputForm::validateDefinition( $definition ) ) !== true )
3.  {
4.      // do something with the error type and error message in $returnValue
5.  }
6.  else
7.  {
8.      // the definition was correct
9.  }
10.  ?>

This method constructs a new ezcInputForm with three parameters. The $inputSource parameter selects the input source and should be one of the constants INPUT_GET, INPUT_POST or INPUT_COOKIE. The $definition parameter is an array of ezcInputFormDefinitionElement items and determines which input variables make up this form (see the example at the top of this class). The last parameter, $characterEncoding is the character encoding to use while retrieving input variable data. This parameter has currently no function as it will depend on PHP 6 functionality which does not exist yet in the input filter extension.

The return value of this function can be used to prefill forms on the next request. It will only work for invalid input fields, as for valid input fields you should never have to get to the original RAW data. In the case a $fieldName is passed that has valid data, an ezcInputFormException will be thrown.