Path

ez components / documentation / api reference / latest / userinput


eZ Components latest

UserInput: ezcInputForm

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcInputForm

Provides access to form variables. [source]
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 ezcInputFormINPUT_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.  ?>

Constants

DEF_ELEMENT_NO_DEFINITION_ELEMENT = 3
DEF_EMPTY = 2
DEF_FIELD_NAME_BROKEN = 8
DEF_NOT_REQUIRED_OR_OPTIONAL = 5
DEF_NO_ARRAY = 1
DEF_UNSUPPORTED_FILTER = 7
DEF_WRONG_FLAGS_TYPE = 6
INVALID = 1
VALID = 0

Properties

string read  $formFields
There is a read-only property for each field that is defined as input field.

Member Variables

protected array $propertyValues
Contains the values of the input variables. The key for each array element is the field name, and the value associated with this key is the property's value. This array does not have an entry for input fields that do not have valid data.

Method Summary

public ezcInputForm __construct( $inputSource, $definition, [$characterEncoding = null] )
Constructs a new ezcInputForm for $inputSource with $definition.
public array(string) getInvalidProperties( )
Returns a list with all properties having invalid data.
public array(string) getOptionalProperties( )
Returns a list with all optional properties.
public array(string) getRequiredProperties( )
Returns a list with all required properties.
public string getUnsafeRawData( $fieldName )
Returns RAW input variable values for invalid field $fieldName.
public array(string) getValidProperties( )
Returns a list with all properties that have valid data.
public static bool hasGetData( )
Returns whether there is GET data available
public bool hasInputField( $fieldName )
Returns whether the optional field $fieldName exists.
public static bool hasPostData( )
Returns whether there is POST data available
public bool hasValidData( $fieldName )
Returns whether the filters for required field $fieldName returned valid data.
public bool isValid( )
Returns whether all the input elements were valid or not.
public static array|bool validateDefinition( $definition )
Validates the definition array $definition.

Methods

__construct

ezcInputForm __construct( int $inputSource, array(ezcInputFormDefinitionElement) $definition, [string $characterEncoding = null] )
Constructs a new ezcInputForm for $inputSource with $definition.
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.

Parameters

Name Type Description
$inputSource int  
$definition array(ezcInputFormDefinitionElement)  
$characterEncoding string  

Throws

ClassDescription
ezcInputFormInvalidDefinitionException when the definition array is invalid or when the input source was invalid.
ezcInputFormVariableMissingException when one of the required input variables is missing.

getInvalidProperties

array(string) getInvalidProperties( )
Returns a list with all properties having invalid data.

getOptionalProperties

array(string) getOptionalProperties( )
Returns a list with all optional properties.

getRequiredProperties

array(string) getRequiredProperties( )
Returns a list with all required properties.

getUnsafeRawData

string getUnsafeRawData( string $fieldName )
Returns RAW input variable values for invalid field $fieldName.
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.

Parameters

Name Type Description
$fieldName string  

Throws

ClassDescription
ezcInputFormFieldNotFoundException when trying to get data from a property that does not exist.
ezcInputFormValidDataException when trying to get unsafe raw data from a input field with valid data.

getValidProperties

array(string) getValidProperties( )
Returns a list with all properties that have valid data.

hasGetData

bool hasGetData( )
Returns whether there is GET data available

hasInputField

bool hasInputField( string $fieldName )
Returns whether the optional field $fieldName exists.

Parameters

Name Type Description
$fieldName string  

hasPostData

bool hasPostData( )
Returns whether there is POST data available

hasValidData

bool hasValidData( string $fieldName )
Returns whether the filters for required field $fieldName returned valid data.

Parameters

Name Type Description
$fieldName string  

isValid

bool isValid( )
Returns whether all the input elements were valid or not.

validateDefinition

array|bool validateDefinition( array $definition )
Validates the definition array $definition.
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.  ?>

Parameters

Name Type Description
$definition array  

Last updated: Mon, 21 Dec 2009