form_state_values_clean

Versions

7

form_state_values_clean(&$form_state)

Removes internal Form API elements and buttons from submitted form values.

This function can be used when a module wants to store all submitted form values, for example, by serializing them into a single database column. In such cases, all internal Form API values and all form button elements should not be contained, and this function allows to remove them before the module proceeds to storage. Next to button elements, the following internal values are removed:

• form_id
• form_token
• form_build_id
• op

Parameters

&$form_state A keyed array containing the current state of the form, including submitted form values; altered by reference.

Related topics

Form generation

Functions to enable the processing and display of HTML forms.

Code

includes/form.inc, line 1349

<?php
function form_state_values_clean(&$form_state) {
  // Remove internal Form API values.
  unset($form_state['values']['form_id'], $form_state['values']['form_token'], $form_state['values']['form_build_id'], $form_state['values']['op']);

  // Remove button values.
  // form_builder() collects all button elements in a form, keyed by button
  // type. We remove the button value separately for each button element.
  foreach ($form_state['buttons'] as $button_type => $buttons) {
    foreach ($buttons as $button) {
      // Remove this button's value from the submitted form values by finding
      // the value corresponding to this button.
      // We iterate over the #parents of this button and move a reference to
      // each parent in $form_state['values']. For example, if #parents is:
      //   array('foo', 'bar', 'baz')
      // then the corresponding $form_state['values'] part will look like this:
      // array(
      //   'foo' => array(
      //     'bar' => array(
      //       'baz' => 'button_value',
      //     ),
      //   ),
      // )
      // We start by (re)moving 'baz' to $last_parent, so we are able unset it
      // at the end of the iteration. Initially, $values will contain a
      // reference to $form_state['values'], but in the iteration we move the
      // reference to $form_state['values']['foo'], and finally to
      // $form_state['values']['foo']['bar'], which is the level where we can
      // unset 'baz' (that is stored in $last_parent).
      $parents = $button['#parents'];
      $values = &$form_state['values'];
      $last_parent = array_pop($parents);
      foreach ($parents as $parent) {
        $values = &$values[$parent];
      }
      unset($values[$last_parent]);
    }
  }
}
?>

Login or register to post comments