Using form_set_error in the submit handler

Question

I have a multistep form and on each submit I send completed fields off to an external API which returns data about the next step of the form.

The problem is, if I use form_set_error in the submit handler, the form_storage is cleared and so the form resets to the first page.

Here's a arbitrary example;

function example_form($form, &$form_state) {
  if(!isset($form_state['step'])){
    $form_state['step'] = 1;
  }
  $form['test'] = array('#markup' => '<p>Step: ' . $form_state['step'] . '</p>');

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => 'go'
  );
  return $form;
}

function example_form_submit($form, &$form_state) {
  $form_state['rebuild'] = TRUE;
  if($form_state['step'] > 5){
    form_set_error('test', 'error');
    return;
  }
  $form_state['step']++;
}

So this create a form with just a text block displaying the step number and a submit button that takes you to the next step. Until you go past the 5th step at which point it should start to error.

For some reason in my testing this breaks the step count, and on error takes you back to step 2.

moving the form_set_error into the form callback, or into a validate callback fixes the issue, but it would be cleaner if I could call it in the submit handler.

Answer 1

In case it's useful to anyone else, I have a unsatisfactory work around;

Store the error in form_state, and look for them in the form callback.

function example_form($form, &$form_state) {
  // if we had an error in the submit handler, trigger it now
  if(isset($form_state['error']) && $form_state['error']){
    form_set_error('test', 'test');
  }
  if(!isset($form_state['step'])){
    $form_state['step'] = 1;
  }
  $form['test'] = array('#markup' => '<p>Step: ' . $form_state['step'] . '</p>');

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => 'go'
  );
  return $form;
}


function example_submit($form, &$form_state) {

  $form_state['rebuild'] = TRUE;
  if($form_state['step'] > 5){
    //store error and return before the step is increased
    $form_state['error'] = true;
    return;
  }


  $form_state['step']++;
}

Answer 2

form_set_error() isn't supposed to be used in a submit handler; it's part of the validation workflow. From the docs:

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

Emphasis mine.

The point is to use form_set_error() to stop the process from ever reaching the submit handler.

Don't forget, you're validating whether or not the current step is greater than 5. That logic needs to happen in a validation handler. :)

Answer 3

function example_form_validate($form, &$form_state) {
}

Use this function to validate your data when submitting a form

Answer 4

form set error will clear your input, so do not use that function here. Instead, use the drupal_set_message. It is not perfect, but it will work.