A primary use case for forms is validating submitted data.
Zend_Form allows you to validate an entire form, a partial form,
or responses for XmlHttpRequests (AJAX). If the submitted data is not valid, it has
methods for retrieving the various error codes and messages for
elements and sub forms.
To validate a full form, use the isValid() method:
<?php
if (!$form->isValid($_POST)) {
// failed validation
}
isValid() will validate every required element, and any
unrequired element contained in the submitted data.
Sometimes you may need to validate only a subset of the data; for
this, use isValidPartial($data):
<?php
if (!$form->isValidPartial($data)) {
// failed validation
}
isValidPartial() only attempts to validate those items
in the data for which there are matching elements; if an element is
not represented in the data, it is skipped.
When validating elements or groups of elements for an AJAX request,
you will typically be validating a subset of the form, and want the
response back in JSON. processAjax() does
precisely that:
<?php
$json = $form->processAjax($data);
You can then simply send the JSON response to the client. If the
form is valid, this will be a boolean TRUE response. If not, it
will be a javascript object containing key/message pairs, where each
'message' is an array of validation error messages.
For forms that fail validation, you can retrieve both error codes
and error messages, using getErrors() and
getMessages(), respectively:
<?php
$codes = $form->getErrors();
$messages = $form->getMessages();
Note
Since the messages returned by getMessages() are an
array of error code/message pairs, getErrors() is
typically not needed.
You can retrieve codes and error messages for individual elements by simply passing the element name to each:
<?php
$codes = $form->getErrors('username');
$messages = $form->getMessages('username');
Note
Note: When validating elements, Zend_Form sends a
second argument to each element's isValid() method:
the array of data being validated. This can then be used by
individual validators to allow them to utilize other submitted
values when determining the validity of the data. An example
would be a registration form that requires both a password and
password confirmation; the password element could use the
password confirmation as part of its validation.
At times, you may want to specify one or more specific error messages to use instead of the error messages generated by the validators attached to your elements. Additionally, at times you may want to mark the form invalid yourself. This functionality is possible via the following methods.
addErrorMessage($message): add an error message to display on form validation errors. You may call this more than once, and new messages are appended to the stack.addErrorMessages(array $messages): add multiple error messages to display on form validation errors.setErrorMessages(array $messages): add multiple error messages to display on form validation errors, overwriting all previously set error messages.getErrorMessages(): retrieve the list of custom error messages that have been defined.clearErrorMessages(): remove all custom error messages that have been defined.markAsError(): mark the form as having failed validation.addError($message): add a message to the custom error messages stack and flag the form as invalid.addErrors(array $messages): add several messages to the custom error messages stack and flag the form as invalid.setErrors(array $messages): overwrite the custom error messages stack with the provided messages and flag the form as invalid.
All errors set in this fashion may be translated.
There are scenarios when you want to allow your user to work on a valid form in several steps. Meanwhile you allow the user to save the form with any set of values inbetween. Then if all the data is specified you can transfer the model from the building or prototying stage to a valid stage.
You can retrieve all the valid values that match the submitted data by calling:
<?php
$validValues = $form->getValidValues($_POST);