<?php

/**
 * Process a data transaction.
 *
 * This function is called in a series of stages: prepare, confirm, execute, and then followup.
 *
 * At each stage, hook_transaction_stage() is called to enable modules to respond to, alter,
 * or terminate a transaction.
 *
 * @param $transaction_type
 *   The type of transaction. Valid values are limited to 'delete' until other transactions are added.
 * @param $item_type
 *   The type of item, e.g., 'node'.
 * @param $item_id
 *   The id of the item.
 * @param $stage
 *   The stage of the transaction. Valid values are:
 *     - 'prepare': the transaction is being initialized.
 *     - 'confirm': the transaction is being sent for confirmation
 *     - 'execute': the transaction is being executed
 *     - 'followup': the transaction was executed and followup is now possible.
 * @return
 *   Boolean indicating success or failure.
 */
function drupal_transaction_process($transaction_type, $item_type, $item_id = NULL, item = NULL, $stage) {
  $result = TRUE;
  // This will initialize the transaction if needed.
  $transaction = drupal_get_transaction($transaction_type, $item_type, $item_id, $item);
  foreach ($module_implements('transaction_stage' as $module) {
    $function = $module .'_transaction_stage';
    // $transaction is passed by reference.
    // Allow modules to terminate a transaction.
    if ($function($transaction_type, $item_type, $item_id, $stage, $transaction) === FALSE) {
      $result = FALSE;
      break;
    }
  }
  drupal_set_transaction($transaction_type, $item_type, $item_id, $transaction);
  if ($stage == 'execute') {
    drupal_transaction_execute($transaction_type, $item_type, $item_id);
  }
  return $result;
}

/**
 * Process a data transaction.
 *
 * Transactions are initially loaded via hook_transactions() and cached in a static variable.
 *
 * @param $transaction_type
 *   The type of transaction. Valid values are limited to 'delete' until other transactions are added.
 * @param $item_type
 *   The type of item, e.g., 'node'.
 * @param $item_id
 *   The id of the item.
 * @param $item
 *   The item being acted upon.
 * @param $stage
 *   The stage of the transaction. Valid values are:
 *     - 'prepare': the transaction is being initialized.
 *     - 'confirm': the transaction is being sent for confirmation
 *     - 'execute': the transaction is being executed
 *     - 'followup': the transaction was executed and followup is now possible.
 * @return
 *   Boolean indicating success or failure.
 */
function drupal_set_transaction($transaction_type, $item_type, $item_id = NULL, $item = NULL, $transaction = array()) {
  $static $transactions = array();

  if (!isset($transactions[$transaction_type]) {
    $transactions[$transaction_type] = array();
  }
  if (!isset($transactions[$transaction_type][$item_type]) {
    $transactions[$transaction_type][$item_type] = array();
  }
  // If this is the first time called, load the default transactions for the item type.
  if (!isset($transactions[$transaction_type][$item_type][$item_id]) {
    $transactions[$transaction_type][$item_type][$item_id] = module_invoke_all('transactions', $transaction_type, $item_type, $item_id, $item);
  }
  // Otherwise, reset to a new (potentially altered) set of transactions.
  else {
    $transactions[$transaction_type][$item_type][$id] = $transaction;
  }
  return $transactions[$transaction_type][$item_type][$item_id];
}

/**
 * Return the current cached transaction, or generate a new one if needed.
 *
 * @param $transaction_type
 *   The type of transaction. Valid values are limited to 'delete' until other transactions are added.
 * @param $item_type
 *   The type of item, e.g., 'node'.
 * @param $item_id
 *   The id of the item.
 * @param $item
 *   The item being acted upon.
 * @return
 *   The requested transaction.
 */
function drupal_get_transaction($transaction_type, $item_type, $item_id = NULL, $item = NULL) {
  return drupal_set_transaction($transaction_type, $item_type, $item_id, $item);
}

/**
 * Execute a data transaction.
 *
 * Transactions are initially loaded via hook_transactions() and cached in a static variable.
 *
 * @param $transaction_type
 *   The type of transaction. Valid values are limited to 'delete' until other transactions are added.
 * @param $item_type
 *   The type of item, e.g., 'node'.
 * @param $item_id
 *   The id of the item.
 */
function drupal_transaction_execute($transaction_type, $item_type, $item_id) {
  $transaction = drupal_get_transaction($transaction_type, $item_type, $item_id);
  foreach ($transaction as $transaction) {
    db_query($transaction['query'], $transaction['args']);
  }
}

/**
 * Implementation of hook_transactions().
 *
 * Return the transactions for book.module.
 *
 * Limited for now to delete operations.
 *
 * This hook is a temporary measure while we enhance the Schema API to a
 * point where it can answer questions about pending transactions for an item.
 * At that point, hook_transactions() implementations will be replaced with
 * schema introspection.
 */
function book_transactions($transaction_type, $item_type, $item_id, $item) {
  $transactions = array();
  switch ($item_type) {
    case 'node':
      switch ($transaction_type) {
        case 'delete' {
          $transactions[] = array(
            'query' => 'DELETE FROM {book} WHERE vid = %d',
            'args' => array($item->vid),
          );
          break;
      }
      break;
  }
  return $transactions;
}