delete API

/** * Perform a deletion from the drupal database.  Call this function if the deletion * being performed is in response to a previous deletion in a package (ex. the deletion of a * comment when it's relevant node is deleted), or when this is an isolated deletion that isn't part * of any deletion package. * * @param $id A unique string identifier for the deletion statement being performed, or one of the following special values: *      'message' =>  Optional.  Pass a message to a deletion package.  Message type and details are passed in the $data array. *      'new package' => Used to begin a new deletion package. Most often this will not be necessary, as most non-core deletions will already be part of a package. *      'confirm' => Initiates the confirmation cycle of a deletion.  This command fully builds all packages for deletion. If any confirmation messages are found, an form array is returned which can be used to print a confirmation screen.  If no confirmation messages are found, the package is executed. *      'execute' => Initiates the actual deletion.  Confirmation messages are bypassed, but abort messages are respected. * @param $data An array of data to pass to the API.  For messages the required elements are: *      'package_id' => The package ID that the message is to be associated with. *      'type' => Any of the following message types: *          'confirm' => Sent to the confirmation code as the result of a confirmation cycle.  The message may be either a translated string, or an array of form elements. *          'abort' => Sent to the execute code to prevent deletion of a package. *      'message' => The message to send. * * Also, any other metadata can be passed in $data that may be useful for other modules during the deletion cycle -- it will be available for both hook_delete_pre() and hook_delete_execute(). * * @param $query The deletion query to be performed, properly escaped. ex. <em>'DELETE FROM {comment} WHERE nid = %d', $nid</em> */function drupal_delete($id, $data = array(), $query = NULL) {  static $delete_id = NULL;  static $is_package = NULL;  static $deletion_data = array();  static $messages = array();  // Package message.  if ($id == 'message') {    if ($data['type'] == 'abort') {      $messages['abort'][$data['package_id']][] = $data['message'];    }    else {      $messages['confirm'][$data['package_id']][] = $data['message'];    }  }  // New package -- mark it as such and get the next deletion ID.  elseif ($id == 'new package') {    $delete_id = db_next_id('delete_id');    $is_package = TRUE;  }  // Execute all packages.  elseif ($id == 'confirm') {    $confirm = TRUE;  }  // Execute all packages.  elseif ($id == 'execute') {    $execute = TRUE;  }  // This is a new deletion to add to a package  else {    // Grab the args for the deletion query itself.    $all_args = func_get_args();    if (count($all_args) > 3) {      $args = array_slice($all_args, 3);    }    else {      $args = array();    }    // Add the information for this deletion into the package array.    $deletion_data[$delete_id][] = array('id' => $id, 'data' => $data, 'query' => $query, 'args' => $args);    // Special case for single deletions.    if (!isset($is_package)) {      $delete_id = db_next_id('delete_id');      $execute = TRUE;    }  }  // Confirm constructed packages.  if ($confirm) {    // Allow modules to inject information into a confirm screen.    module_invoke_all('delete_pre', $deletion_data);    // Messages exist.    if (count($messages['confirm'])) {      $form = array();      foreach ($messages['confirm'] as $package_id => $messages) {        foreach ($messages as $key => $message) {          // Either form elements or markup can be inserted.          if (is_array($message)) {            $form += $message;          }          else {            $form[$package_id][$key] = array('#value' => $message);          }        }      }      return $form;    }    // No confirm messages found, so execute the package.    else {      $execute = TRUE;    }  }  // Execute all constructed packages.  if ($execute) {    // Allow modules to inject information into a confirm screen, or prevent the deletion altogether    module_invoke_all('delete_pre', $deletion_data);    // Some messages were generated.    if (count($messages)) {      // Process the confirm messages for each package.      if (count($messages['confirm']) && !$edit['confirm']) {      }      // Process the abort messages for each package--they cancel out deletion of the package.      foreach ($messages['abort'] as $package_id => $abort_messages) {        drupal_set_message(theme('item_list', $abort_messages), 'error');        // Unset this package from the $deletion_data array, since it's deletion was aborted.        unset($deletion_data[$package_id]);        unset($messages['abort'][$package_id], $messages['confirm'][$package_id]);      }    }    drupal_delete_execute($deletion_data);    unset ($is_package, $delete_id, $deletion_data, $messages);  }}/** * Internal function which executes all the database deletions in all packages of a a single page call. * * @param $deletion_data The complete array of deletion data for all packages. */function drupal_delete_execute($deletion_data) {  // Allow modules to perform any operations just prior to the deletion of the packages.  module_invoke_all('delete_execute', $deletion_data);  foreach ($deletion_data as $delete_id => $data) {    foreach ($data as $deletion) {      db_query($deletion['query'], $deletion['args']);    }  }}