## Apache Zeta Components Manual :: Docs For Class ezcInputForm

### UserInput::ezcInputForm

### Class ezcInputForm

Provides access to form variables.

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

Source for this file: /UserInput/src/input_form.php

Version: | //autogentag//

### 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 static bool | `hasGetData( )` Returns whether there is GET data available
public static bool | `hasPostData( )` Returns whether there is POST data available
public static array|bool | `validateDefinition( $definition )` Validates the definition array $definition.
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 bool | `hasInputField( $fieldName )` Returns whether the optional field $fieldName exists.
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.

### Methods

#### hasGetData

static bool hasGetData( )

Returns whether there is GET data available

#### hasPostData

static bool hasPostData( )

Returns whether there is POST data available

#### validateDefinition

static 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 |

#### __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 |

##### Exceptions:

Type | Description
--- | ---
`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 |

##### Exceptions:

Type | Description
--- | ---
`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.

#### hasInputField

bool hasInputField( string $fieldName )

Returns whether the optional field $fieldName exists.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$fieldName` | string |

#### 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.

Documentation generated by phpDocumentor 1.4.3