What is the difference between drupal_get_form() and drupal_retrieve_form()? Can someone explain the difference? I look at the API, but the description seems similar to me.

  • I think one key difference is that drupal_retrieve_form() allows your code to access the updated $form_state as it's passed by reference, however drupal_get_form() just return the $form, not the state.
    – Felix Eve
    Apr 7, 2016 at 0:32

1 Answer 1


The difference is that drupal_get_form() handles retrieving, processing, and displaying a rendered HTML form for modules automatically, while drupal_retrieve_form() returns the structured array that defines a form.

Retrieving the form

drupal_get_form() first checks if the form is present in the form cache with form_get_cache(); if it isn't present, it calls drupal_retrieve_form(), and drupal_prepare_form().

Processing the form

drupal_get_form() calls drupal_process_form(), which is the function that calls drupal_validate_form(), and that invokes the submission handlers with form_execute_handlers().

Rendering the form

The rendering is done from drupal_process_form(), which calls form_builder().

In most of the cases, drupal_get_form() is the function to use, such as in the following code.

function node_menu() {
  $items['admin/content'] = array(
    'title' => 'Content', 
    'description' => 'Find and manage content.', 
    'page callback' => 'drupal_get_form', 
    'page arguments' => array('node_admin_content'), 
    'access arguments' => array('access content overview'), 
    'weight' => -10, 
    'file' => 'node.admin.inc',

  // …

  return $items;

The only module I found that is calling drupal_retrieve_form() directly is the Mollom module in mollom_moderate(), which uses it for automatically submitting a form. The code could use drupal_form_submit(), but (as a comment says), "Programmatic form submissions are not able to automatically use the primary form submit button/action, so we need to resemble drupal_form_submit()."

  $form_id = $form_info['delete form'];
  $form_state = form_state_defaults();
  // We assume that all delete confirmation forms take the fully loaded
  // entity as (only) argument.
  $messages[] = "Attempt to load $form_info[entity] entity via entity_load().";
  $entities = entity_load($data->entity, array($data->id));
  $form_state['build_info']['args'][] = $entities[$data->id];
  $form = drupal_retrieve_form($form_id, $form_state);

  $form_state['values'] = array();
  $form_state['values']['mollom']['feedback'] = '';
  // Take over the primary submit button of confirm_form().
  $form_state['values']['op'] = $form['actions']['submit']['#value'];

  $form_state['input'] = $form_state['values'];
  $form_state['programmed'] = TRUE;
  // Programmed forms are always submitted.
  $form_state['submitted'] = TRUE;

  // Reset form validation.
  $form_state['must_validate'] = TRUE;

  drupal_prepare_form($form_id, $form, $form_state);
  drupal_process_form($form_id, $form, $form_state);

  $result = $form_state['executed'];

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.