Why is submit handler not called if $state['rebuild'] == true?

Question

I have a simple form that shows a form fields and after submitting shows just a download link:

function activit_report_download_file_form($form, &$state, $node) {

// check if form was already submitted
$submitted = false;
if(isset($state['triggering_element'])) {
  $submitted = true;

  if(!valid_email_address($state['values']['email'])) { $submitted = false; }
  if(strlen($state['values']['name'])<2) { $submitted = false; }
  if(strlen($state['values']['surname'])<2) { $submitted = false; }
}

if(!user_is_logged_in() && !$submitted) {

  $form['info'] = array(
      '#type' => 'markup',
      '#markup' => '<div class="info">'.t('Po vyplnení Vaších údajov si budete môcť stiahnuť PDF report').'</div><br>'
  );

  $form['email'] = array(
      '#type' => 'textfield',
      '#attributes' => array('placeholder' => t('Váš email'))
  );

  $form['name'] = array(
      '#type' => 'textfield',
      '#attributes' => array('placeholder' => t('Váše meno'))
  );

  $form['surname'] = array(
      '#type' => 'textfield',
      '#attributes' => array('placeholder' => t('Váše priezvisko'))
  );

  $form['submit'] = array(
      '#type' => 'submit',
      '#value' => t('Získať link na stiahnutie reportu'),
      '#attributes' => array('class' => array('button', 'btn-blue')),

  );

} else {

  $form['link'] = array(
      '#type' => 'markup',
      '#markup' => '
        <div class="info">Report stiahnete kliknutím na toto tlačítko.</div><br>
        <a href="" class="button btn-orange">'.t('Stiahnuť PDF report').'</a>'
  );

}

return $form;
}

In validation handler is $state['rebuild'] = true;

function activit_report_download_file_form_validate($form, &$state) {

  $state['rebuild'] = true;

}

In submit handler is:

function activit_report_download_file_form_submit($form, &$state) {

  db_insert('t_report_download')->fields(array(
      'email' => $state['values']['email'],
      'name' => $state['values']['name'],
      'surname' => $state['values']['surname'],
      'anonymous' => 1,
  ))->execute();

  dsm('submitted');
}

Problem is that submit handler is triggered only if $state['rebuild'] = true; in validation handler is commented. If it is not, submit handler will never be triggered.

What's the logic behind this behavior?

Answer 1

When form validation fails submit handler should not be executed because there are errors in the form.

In a similar way, when a form is mark as rebuild in the validation phase submit handlers should not be executed because the form is going to be rebuilt. This means that form is going to change and the user interaction with the form is not finished.

You can check the (complex) workflow of FAPI in this illustration: (Illustration from https://www.drupal.org/node/165104)