form_set_error

  1. drupal
    1. 5
    2. 6
    3. 7
    4. 8
Versions
5 form_set_error($name = NULL, $message = '')
6 form_set_error($name = NULL, $message = '', $reset = FALSE)
8 – 7 form_set_error($name = NULL, $message = '', $limit_validation_errors = NULL)

Files an error against a form element.

When a validation error is detected, the validator calls form_set_error() to indicate which element needs to be changed and provide an error message. This causes the Form API to not execute the form submit handlers, and instead to re-display the form to the user with the corresponding elements rendered with an 'error' CSS class (shown as red by default).

The standard form_set_error() behavior can be changed if a button provides the #limit_validation_errors property. Multistep forms not wanting to validate the whole form can set #limit_validation_errors on buttons to limit validation errors to only certain elements. For example, pressing the "Previous" button in a multistep form should not fire validation errors just because the current step has invalid values. If #limit_validation_errors is set on a clicked button, the button must also define a #submit property (may be set to an empty array). Any #submit handlers will be executed even if there is invalid input, so extreme care should be taken with respect to any actions taken by them. This is typically not a problem with buttons like "Previous" or "Add more" that do not invoke persistent storage of the submitted form values. Do not use the #limit_validation_errors property on buttons that trigger saving of form values to the database.

The #limit_validation_errors property is a list of "sections" within $form_state['values'] that must contain valid values. Each "section" is an array with the ordered set of keys needed to reach that part of $form_state['values'] (i.e., the #parents property of the element).

Example 1: Allow the "Previous" button to function, regardless of whether any user input is valid.

<?php
  $form['actions']['previous'] = array(
    '#type' => 'submit',
    '#value' => t('Previous'),
    '#limit_validation_errors' => array(),       // No validation.
    '#submit' => array('some_submit_function'),  // #submit required.
  );
?>

Example 2: Require some, but not all, user input to be valid to process the submission of a "Previous" button.

<?php
  $form['actions']['previous'] = array(
    '#type' => 'submit',
    '#value' => t('Previous'),
    '#limit_validation_errors' => array(
      array('step1'),       // Validate $form_state['values']['step1'].
      array('foo', 'bar'),  // Validate $form_state['values']['foo']['bar'].
    ),
    '#submit' => array('some_submit_function'), // #submit required.
  );
?>

This will require $form_state['values']['step1'] and everything within it (for example, $form_state['values']['step1']['choice']) to be valid, so calls to form_set_error('step1', $message) or form_set_error('step1][choice', $message) will prevent the submit handlers from running, and result in the error message being displayed to the user. However, calls to form_set_error('step2', $message) and form_set_error('step2][groupX][choiceY', $message) will be suppressed, resulting in the message not being displayed to the user, and the submit handlers will run despite $form_state['values']['step2'] and $form_state['values']['step2']['groupX']['choiceY'] containing invalid values. Errors for an invalid $form_state['values']['foo'] will be suppressed, but errors flagging invalid values for $form_state['values']['foo']['bar'] and everything within it will be flagged and submission prevented.

Partial form validation is implemented by suppressing errors rather than by skipping the input processing and validation steps entirely, because some forms have button-level submit handlers that call Drupal API functions that assume that certain data exists within $form_state['values'], and while not doing anything with that data that requires it to be valid, PHP errors would be triggered if the input processing and validation steps were fully skipped.

Parameters

$name The name of the form element. If the #parents property of your form element is array('foo', 'bar', 'baz') then you may set an error on 'foo' or 'foo][bar][baz'. Setting an error on 'foo' sets an error for every element where the #parents array starts with 'foo'.

$message The error message to present to the user.

$limit_validation_errors Internal use only. The #limit_validation_errors property of the clicked button, if it exists.

Return value

Return value is for internal use only. To get a list of errors, use form_get_errors() or form_get_error().

See also

http://drupal.org/node/370537

http://drupal.org/node/763376

Related topics

▾ 98 functions call form_set_error()

action_example_node_sticky_action_validate in examples/action_example/action_example.module
Validates settings form for action_example_node_sticky_action(). Verifies that user exists before continuing.
aggregator_form_category_validate in modules/aggregator/aggregator.admin.inc
Validate aggregator_form_feed form submissions.
aggregator_form_feed_validate in modules/aggregator/aggregator.admin.inc
Validate aggregator_form_feed() form submissions.
aggregator_form_opml_validate in modules/aggregator/aggregator.admin.inc
Validate aggregator_form_opml form submissions.
ajax_example_dynamic_sections_validate in examples/ajax_example/ajax_example_graceful_degradation.inc
Validation function for ajax_example_dynamic_sections().
authorize_filetransfer_form_validate in includes/authorize.inc
Validate callback for the filetransfer authorization form.
block_add_block_form_validate in modules/block/block.admin.inc
Form validation handler for the add block form.
block_admin_configure_validate in modules/block/block.admin.inc
Form validation handler for the block configuration form.
book_admin_edit_validate in modules/book/book.admin.inc
Check that the book has not been changed while using the form.
book_admin_settings_validate in modules/book/book.admin.inc
Validate the book settings form.
color_scheme_form_validate in modules/color/color.module
Validation handler for color change form.
comment_admin_overview_validate in modules/comment/comment.admin.inc
Validate comment_admin_overview form submissions.
comment_form_validate in modules/comment/comment.module
Validate comment form submissions.
contact_category_edit_form_validate in modules/contact/contact.admin.inc
Validate the contact category edit page form submission.
contact_personal_form_validate in modules/contact/contact.pages.inc
Form validation handler for contact_personal_form().
contact_site_form_validate in modules/contact/contact.pages.inc
Form validation handler for contact_site_form().
dblog_filter_form_validate in modules/dblog/dblog.admin.inc
Validate result from dblog administration filter form.
drupal_validate_form in includes/form.inc
Validates user-submitted form data from the $form_state using the validate functions defined in a structured form array.
email_example_form_validate in examples/email_example/email_example.module
Form validation logic for the contact form.
file_managed_file_save_upload in modules/file/file.module
Given a managed_file element, save any files that have been uploaded into it.
file_save_upload in includes/file.inc
Saves a file upload to a new location.
filter_admin_format_form_validate in modules/filter/filter.admin.inc
Validate text format form submissions.
form_error in includes/form.inc
Flag an element as having an error.
form_example_tutorial_10_validate in examples/form_example/form_example_tutorial.inc
Validate handler for form_example_tutorial_10().
form_example_tutorial_6_validate in examples/form_example/form_example_tutorial.inc
Now we add a handler/function to validate the data entered into the "year of birth" field to make sure it's between the values of 1900 and 2000. If not, it displays an error. The value report is $form_state['values'] (see…
form_example_tutorial_7_validate in examples/form_example/form_example_tutorial.inc
Validation function for form_example_tutorial_7().
form_example_tutorial_8_next_validate in examples/form_example/form_example_tutorial.inc
Validate handler for the next button on first page.
form_example_tutorial_9_validate in examples/form_example/form_example_tutorial.inc
Validate function for form_example_tutorial_9().
form_example_wizard_location_info_validate in examples/form_example/form_example_wizard.inc
Custom validation form for the 'location info' page of the wizard.
form_get_error in includes/form.inc
Returns the error message filed against the given form element.
form_get_errors in includes/form.inc
Return an associative array of all errors.
form_test_element_validate_name in modules/simpletest/tests/form_test.module
Form element validation handler for 'name' in form_test_validate_form().
form_test_programmatic_form_validate in modules/simpletest/tests/form_test.module
Form validation handler for programmatic form submissions.
form_test_validate_form_validate in modules/simpletest/tests/form_test.module
Form validation handler for form_test_validate_form().
forum_node_validate in modules/forum/forum.module
Implements hook_node_validate().
hook_node_validate in modules/node/node.api.php
Perform node validation before a node is created or updated.
hook_prepare in modules/node/node.api.php
Act on a node object about to be shown on the add/edit form.
hook_validate in modules/node/node.api.php
Perform node validation before a node is created or updated.
image_example_style_form_validate in examples/image_example/image_example.pages.inc
Verifies that the user supplied an image with the form..
image_gd_settings in modules/system/image.gd.inc
Retrieve settings for the GD2 toolkit.
image_gd_settings_validate in modules/system/image.gd.inc
Validate the submitted GD settings.
image_style_name_validate in modules/image/image.admin.inc
Element validate function to ensure unique, URL safe style names.
install_settings_form_validate in includes/install.core.inc
Form API validate for install_settings form.
locale_languages_edit_form_validate in modules/locale/locale.admin.inc
Validate the language editing form. Reused for custom language addition too.
locale_languages_predefined_form_validate in modules/locale/locale.admin.inc
Validate the language addition form.
locale_translate_edit_form_validate in modules/locale/locale.admin.inc
Validate string editing form submissions.
locale_translation_filter_form_validate in modules/locale/locale.admin.inc
Validate result from locale translation filter form.
menu_edit_item_validate in modules/menu/menu.admin.inc
Validate form values for a menu link being added or edited.
nodeapi_example_node_validate in examples/nodeapi_example/nodeapi_example.module
Implements hook_node_validate().
node_admin_nodes_validate in modules/node/node.admin.inc
Validate node_admin_nodes form submissions.
node_assign_owner_action_validate in modules/node/node.module
Validates settings form for node_assign_owner_action().
node_type_form_validate in modules/node/content_types.inc
Form validation handler for node_type_form().
node_validate in modules/node/node.module
Perform validation checks on the given node.
openid_begin in modules/openid/openid.module
The initial step of OpenID authentication responsible for the following:
openid_user_add_validate in modules/openid/openid.pages.inc
path_admin_form_validate in modules/path/path.admin.inc
Verify that a URL alias is valid
path_form_element_validate in modules/path/path.module
Form element validation handler for URL alias form element.
poll_validate in modules/poll/poll.module
Implements hook_validate().
poll_view_voting_validate in modules/poll/poll.module
Validation function for processing votes
profile_field_form_validate in modules/profile/profile.admin.inc
Validate profile_field_form submissions.
profile_user_form_validate in modules/profile/profile.module
Form validation handler for the user register/profile form.
SearchQuery::executeFirstPass in modules/search/search.extender.inc
Executes the first pass query.
search_admin_settings_validate in modules/search/search.admin.inc
Form validation handler for search_admin_settings().
search_box_form_submit in modules/search/search.module
Process a block search form submission.
search_form in modules/search/search.module
Builds a search form.
search_form_submit in modules/search/search.pages.inc
Process a search form submission.
shortcut_link_edit_validate in modules/shortcut/shortcut.admin.inc
Validation handler for the shortcut link add and edit forms.
shortcut_set_add_form_validate in modules/shortcut/shortcut.admin.inc
Validation handler for shortcut_set_add_form().
shortcut_set_edit_form_validate in modules/shortcut/shortcut.admin.inc
Validation handler for shortcut_set_edit_form().
shortcut_set_switch_validate in modules/shortcut/shortcut.admin.inc
Validation handler for shortcut_set_switch().
simpletest_settings_form_validate in modules/simpletest/simpletest.pages.inc
Validation handler for simpletest_settings_form().
system_add_date_formats_form_validate in modules/system/system.admin.inc
Validate new date format string submission.
system_add_date_format_type_form_validate in modules/system/system.admin.inc
Validate system_add_date_format_type form submissions.
system_check_directory in modules/system/system.module
Checks the existence of the directory specified in $form_element.
system_ip_blocking_form_validate in modules/system/system.admin.inc
system_send_email_action_validate in modules/system/system.module
Validate system_send_email_action form submissions.
system_site_information_settings_validate in modules/system/system.admin.inc
Validates the submitted site-information form.
system_theme_settings_validate in modules/system/system.admin.inc
Validator for the system_theme_settings() form.
taxonomy_form_term_validate in modules/taxonomy/taxonomy.admin.inc
Validation handler for the term form.
taxonomy_form_vocabulary_validate in modules/taxonomy/taxonomy.admin.inc
Form validation handler for taxonomy_form_vocabulary().
translation_node_validate in modules/translation/translation.module
Implements hook_node_validate().
trigger_assign_form_validate in modules/trigger/trigger.admin.inc
Validation function for trigger_assign_form().
update_manager_install_form_submit in modules/update/update.manager.inc
Handle form submission when installing new projects via the update manager.
update_manager_install_form_validate in modules/update/update.manager.inc
Validate the form for installing a new project via the update manager.
update_manager_update_form_validate in modules/update/update.manager.inc
Validation callback to ensure that at least one project is selected.
update_settings_validate in modules/update/update.settings.inc
Validation callback for the settings form.
user_account_form_validate in modules/user/user.module
Form validation handler for user_account_form().
user_admin_account_validate in modules/user/user.admin.inc
user_admin_role_validate in modules/user/user.admin.inc
Form validation handler for the user_admin_role() form.
user_admin_settings in modules/user/user.admin.inc
Form builder; Configure user settings for this site.
user_login_final_validate in modules/user/user.module
The final validation handler on the login form.
user_login_name_validate in modules/user/user.module
A FAPI validate handler. Sets an error if supplied username has been blocked.
user_pass_validate in modules/user/user.pages.inc
user_validate_current_pass in modules/user/user.module
Form validation handler for the current password on the user_account_form().
user_validate_picture in modules/user/user.module
Validates an image uploaded by a user.
_field_ui_field_overview_form_validate_add_existing in modules/field_ui/field_ui.admin.inc
Helper function for field_ui_field_overview_form_validate.
_field_ui_field_overview_form_validate_add_new in modules/field_ui/field_ui.admin.inc
Helper function for field_ui_field_overview_form_validate.
_form_validate in includes/form.inc
Performs validation on form elements. First ensures required fields are completed, #maxlength is not exceeded, and selected options were in the list of options given to the user. Then calls user-defined validators.

Code

includes/form.inc, line 1532

<?php
function form_set_error($name = NULL, $message = '', $limit_validation_errors = NULL) {
  $form = &drupal_static(__FUNCTION__, array());
  $sections = &drupal_static(__FUNCTION__ . ':limit_validation_errors');
  if (isset($limit_validation_errors)) {
    $sections = $limit_validation_errors;
  }

  if (isset($name) && !isset($form[$name])) {
    $record = TRUE;
    if (isset($sections)) {
      // #limit_validation_errors is an array of "sections" within which user
      // input must be valid. If the element is within one of these sections,
      // the error must be recorded. Otherwise, it can be suppressed.
      // #limit_validation_errors can be an empty array, in which case all
      // errors are suppressed. For example, a "Previous" button might want its
      // submit action to be triggered even if none of the submitted values are
      // valid.
      $record = FALSE;
      foreach ($sections as $section) {
        // Exploding by '][' reconstructs the element's #parents. If the
        // reconstructed #parents begin with the same keys as the specified
        // section, then the element's values are within the part of
        // $form_state['values'] that the clicked button requires to be valid,
        // so errors for this element must be recorded. As the exploded array
        // will all be strings, we need to cast every value of the section
        // array to string.
        if (array_slice(explode('][', $name), 0, count($section)) === array_map('strval', $section)) {
          $record = TRUE;
          break;
        }
      }
    }
    if ($record) {
      $form[$name] = $message;
      if ($message) {
        drupal_set_message($message, 'error');
      }
    }
  }

  return $form;
}
?>