What is the purpose and differences between drupal_goto(),drupal_redirect_form() and $form_state['redirect']?

Question

May you explain me the differences between drupal_goto(), drupal_redirect_form() and $form_state['redirect'] with examples?

How can I pass the form values with these functions, and how can I retrieve the values using $_GET and $_POST in Drupal 7? Which is the better one to use?

Answer 1

First off, drupal_redirect_form() is not a function that a third-party module should use; it's a function used by Drupal code, and it is only used from two Drupal functions. In your code you should use drupal_goto(), or $form_state['redirect'].

The difference between drupal_goto(), and $form_state['redirect'] is that a form submission handler should never use drupal_goto(), which should be used, for example, from a page callback for a page without forms. The main reason not to use drupal_goto() in a form submission handler is that calling it would stop the other form submission handlers to be invoked. drupal_goto() contains the following code:

  // Drupal 6.
  // Even though session_write_close() is registered as a shutdown function, we
  // need all session data written to the database before redirecting.
  session_write_close();

  header('Location: ' . $url, TRUE, $http_response_code);

  // The "Location" header sends a redirect status code to the HTTP daemon. In
  // some cases this can be wrong, so we make sure none of the code below the
  // drupal_goto() call gets executed upon redirection.
  exit();

  // Drupal 7.
  header('Location: ' . $url, TRUE, $http_response_code);

  // The "Location" header sends a redirect status code to the HTTP daemon. In
  // some cases this can be wrong, so we make sure none of the code below the
  // drupal_goto() call gets executed upon redirection.
  drupal_exit($url);  

Both exit() and drupal_exit() cause Drupal to stop running, and the output be returned to the browser; this means that other form submission handlers are not executed. Even if the form submission handler is for a form you use in your own module, you cannot know for sure how many form submission handlers need to be executed, and if your form submission handler is effectively the last one to be executed; other modules can add any form submission handler to your form. Using drupal_goto(), you are also avoiding that other Drupal code is executed; this could have any collateral effect, in the case of forms.

As per passing values to the page where the user is redirected, you can use code similar to the following one.

$form_state['redirect'] = array(
  $redirect_path,
  array(
    'query' => array(
      'foo' => $form_state['values']['foo'],
    ),
  ),
);

This snippet would cause the user to be redirect to http://your.site.domain/$redirect_path?foo=$form_state['values']['foo']. That page will get the value of $form_state['values']['foo'] in $_GET['foo'].

Consider also that, in the case you need to pass to the page where you are redirecting the user all the values submitted by the user in the form, you probably need to rewrite the code you wrote. If the page to which you are redirecting the user needs those values to, e.g., save them in the database, then that code should be in the form submission handler, and not in the other page callback. If the page needs those values to output HTML, then the form submission handler could render the output, and save it in a session variable, which is then used from the new page handler to show its own output.
In any case, all the values submitted from users in the form should not be passed to another page handler through $_GET or $_POST. Passing some of the submitted values is fine, though.