Apache Zeta Components - high quality PHP components

Tutorial
API

eZ Components - UserInput

Introduction
Class overview
Basic usage
More information

Introduction

The UserInput component facilitates the secure handling of input data. With a user-defined form definition, the component analyzes, filters and returns GET and POST data. The component will not render forms to HTML from its definition, but only handle incoming data. Filtering is done through PHP's filter extension; accordingly, UserInput supports all filters and flags that this extension supports.

Class overview

ezcInputForm: This class validates the definition, processes the form data and provides functionality for accessing the submitted data.
ezcInputFormDefinitionElement: This container class wraps around the definition for each form element. It contains information about whether the field is optional or required, the filter name and optional flags for the filter.

Basic usage

The example in this section is separated into multiple parts to allow for easier explanation.

<?php
$definition = array(
'firstName' => new ezcInputFormDefinitionElement(
ezcInputFormDefinitionElement::REQUIRED, 'string'
),
'lastName' => new ezcInputFormDefinitionElement(
ezcInputFormDefinitionElement::REQUIRED, 'string'
),
'age' => new ezcInputFormDefinitionElement(
ezcInputFormDefinitionElement::REQUIRED, 'int',
array( 'min_range' => 1, 'max_range' => 99 ),
FILTER_FLAG_ALLOW_HEX
),
'email' => new ezcInputFormDefinitionElement(
ezcInputFormDefinitionElement::REQUIRED, 'validate_email'
),
);
?>

In the lines above, we prepare a definition array that defines our form. A definition array consists of an associative array where the key is the input field name and the value is an object of the ezcInputFormDefinitionElement class.

The first parameter to the constructor is either ezcInputFormDefinitionElement::REQUIRED for fields that must be submitted (although they can be empty) or ezcInputFormDefinitionElement::OPTIONAL for optional fields. The second parameter is the filter to use for the input field. The filters are defined in PHP's filter extension, and can also be retrieved by the PHP function filter_list(). The third optional parameter contains flags to the filter. Those are documented in the filter documentation.

In the definition above, we define four input fields that are all required. Two of them are strings (firstName and lastName), one is an integer (age) and the last one is an e-mail address (email).

<?php
foreach ( $definition as $name => $dummy )
{
$propertyName = "property_$name";
$propertyWarningName = "warning_$name";
$$propertyName = '';
$$propertyWarningName = '';
}
?>

Here, we initialize the variables that are used to show the current value and whether invalid data was submitted to the form. This is used later to render the form.

<?php
if ( ezcInputForm::hasGetData() )
{
$form = new ezcInputForm( INPUT_GET, $definition );
foreach ( $definition as $name => $dummy )
{
$propertyName = "property_$name";
$propertyWarningName = "warning_$name";
if ( $form->hasValidData( $name ) )
{
$$propertyName = $form->$name;
}
else
{
$$propertyName =
htmlspecialchars( $form->getUnsafeRawData( $name ) );
$$propertyWarningName = '[invalid]';
}
}
}
?>

In line 2, we check whether there was GET data submitted to this script. Aside from the ezcInputForm::hasGetData() method to verify if there is GET data available, there is another method, ezcInputForm::hasPostData(), which does the same thing but for POST data. Upon instantiation of the ezcInputForm object in line 4, the component will parse the input data and make the input fields available through the object. In case one of the required input variables does not exist in the input data, this instantiation will throw an ezcInputFormFieldNotFoundException exception.

In lines 6 to 20, we loop over all elements from the definition and check (in line 10) whether the field has valid data. When there is valid data available, we retrieve the value from the $form object through a property (in line 12). In case the data for a field is invalid, we fetch the raw data with the ezcInputForm::getUnsafeRawData() function, encode that with htmlspecialchars and set the parameter with the name "property_<fieldname>" to the encoded raw data. We also record in the "warning_<fieldname>" variable if the field has invalid data.

<form action='tutorial_example_01.php'>
First name: <input type='text' name='firstName' value='<?php echo $property_firstName; ?>'/><?php echo $warning_firstName; ?><br/>
Last name: <input type='text' name='lastName' value='<?php echo $property_lastName; ?>'/><?php echo $warning_lastName; ?><br/>
Age: <input type='text' name='age' value='<?php echo $property_age; ?>'/><?php echo $warning_age; ?><br/>
E-mail: <input type='text' name='email' value='<?php echo $property_email; ?>'/><?php echo $warning_email; ?><br/>
<input type='submit' value='submit'/><br/>
</form>
<?php
// just to make my test script happy
?>

The last part of this example renders the form. If previous data was submitted, it will be shown as the default value in the input fields. If the data for one of the fields is invalid, this will be shown next to the field.

More information

The filters and their parameters are documented in the filter documentation.