<?php

/**
 * @file
 * Defines the payment system and checkout integration.
 */


// Local payment transaction status definitions:

// Pending is used when a transaction has been initialized but is still awaiting
// resolution; e.g. a CC authorization awaiting capture or an e-check payment
// pending at the payment provider.
define('COMMERCE_PAYMENT_STATUS_PENDING', 'pending');

// Success is used when a transaction has completed resulting in money being
// transferred from the customer to the store or vice versa.
define('COMMERCE_PAYMENT_STATUS_SUCCESS', 'success');

// Failure is used when a transaction cannot be completed or is rejected.
define('COMMERCE_PAYMENT_STATUS_FAILURE', 'failure');

// Credit card transaction types definitions:

// Used to just authorize an amount on a credit card account.
define('COMMERCE_CREDIT_AUTH_ONLY', 'authorize');

// User to just capture an amount on a credit card account.
define('COMMERCE_CREDIT_CAPTURE_ONLY', 'capture');

// Used to capture funds from a prior authorization.
define('COMMERCE_CREDIT_PRIOR_AUTH_CAPTURE', 'prior_auth_capture');

// Used to authorize and capture money all at once.
define('COMMERCE_CREDIT_AUTH_CAPTURE', 'auth_capture');

// Used to set up a credit card reference through the payment gateway.
define('COMMERCE_CREDIT_REFERENCE_SET', 'reference_set');

// Used to capture funds using a credit card reference.
define('COMMERCE_CREDIT_REFERENCE_TXN', 'reference_txn');

// Used to remove a reference from the payment gateway.
define('COMMERCE_CREDIT_REFERENCE_REMOVE', 'reference_remove');

// Used to credit funds to a reference at the payment gateway.
define('COMMERCE_CREDIT_REFERENCE_CREDIT', 'reference_credit');

// Used to credit funds to a credit card account.
define('COMMERCE_CREDIT_CREDIT', 'credit');

// Used to void a transaction before the transaction clears.
define('COMMERCE_CREDIT_VOID', 'void');

/**
 * Implements of hook_entity_info().
 */
function commerce_payment_entity_info() {
  $return = array(
    'commerce_payment_transaction' => array(
      'label' => t('Commerce Payment transaction'),
      'controller class' => 'CommercePaymentTransactionEntityController',
      'base table' => 'commerce_payment_transaction',
      'revision table' => 'commerce_payment_transaction_revision',
      'fieldable' => FALSE,
      'entity keys' => array(
        'id' => 'transaction_id',
        'revision' => 'revision_id',
        'bundle' => 'payment_method',
        'label' => 'transaction_id', // TODO: Update to use a custom callback.
      ),
      'bundle keys' => array(
        'bundle' => 'payment_method',
      ),
      'bundles' => array(),
      'load hook' => 'commerce_payment_transaction_load',
      'view modes' => array(
        'administrator' => array(
          'label' => t('Administrator'),
          'custom settings' => FALSE,
        ),
      ),
      'uri callback' => 'commerce_payment_transaction_uri',
      'access callback' => 'commerce_payment_transaction_access',
      'access arguments' => array(
        'user key' => 'uid',
        'access tag' => 'commerce_payment_transaction_access',
      ),
      'token type' => 'commerce-payment-transaction',
      'metadata controller class' => '',
      'permission labels' => array(
        'singular' => t('payment transaction'),
        'plural' => t('payment transactions'),
      ),

      // Prevent Redirect alteration of the payment transaction form.
      'redirect' => FALSE,
    ),
  );

  foreach (commerce_payment_methods() as $method_id => $payment_method) {
    $return['commerce_payment_transaction']['bundles'][$method_id] = array(
      'label' => $payment_method['title'],
    );
  }

  return $return;
}

/**
 * Entity uri callback: gives modules a chance to specify a path for a payment
 * transaction.
 */
function commerce_payment_transaction_uri($transaction) {
  // Allow modules to specify a path, returning the first one found.
  foreach (module_implements('commerce_payment_transaction_uri') as $module) {
    $uri = module_invoke($module, 'commerce_payment_transaction_uri', $transaction);

    // If the implementation returned data, use that now.
    if (!empty($uri)) {
      return $uri;
    }
  }

  return NULL;
}

/**
 * Implements hook_hook_info().
 */
function commerce_payment_hook_info() {
  $hooks = array(
    'commerce_payment_totals_row_info' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_totals_row_info_alter' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_method_info' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_method_info_alter' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_methods' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_transaction_status_info' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_transaction_uri' => array(
      'group' => 'commerce'
    ),
    'commerce_transaction_view' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_transaction_access' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_transaction_insert' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_transaction_update' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_transaction_delete' => array(
      'group' => 'commerce',
    ),
    'commerce_payment_order_paid_in_full' => array(
      'group' => 'commerce',
    ),
  );

  return $hooks;
}

/**
 * Implements hook_permission().
 */
function commerce_payment_permission() {
  return array(
    'administer payment methods' => array(
      'title' => t('Administer payment methods'),
      'description' => t('Allows users to configure enabled payment methods.'),
      'restrict access' => TRUE,
    ),
    'administer payments' => array(
      'title' => t('Administer payments'),
      'description' => t('Allows users to perform any payment action for any order and view transaction payloads.'),
      'restrict access' => TRUE,
    ),
    'view payments' => array(
      'title' => t('View payments'),
      'description' => t('Allows users to view the payments made to an order.'),
      'restrict access' => TRUE,
    ),
    'create payments' => array(
      'title' => t('Create payments'),
      'description' => t('Allows users to create new payments for orders.'),
      'restrict access' => TRUE,
    ),
    'update payments' => array(
      'title' => t('Update payments'),
      'description' => t('Allows users to update payments via payment method specific operations links.'),
      'restrict access' => TRUE,
    ),
    'delete payments' => array(
      'title' => t('Delete payments'),
      'description' => t('Allows users to delete payments on orders they can access.'),
      'restrict access' => TRUE,
    ),
  );
}

/**
 * Implements hook_theme().
 */
function commerce_payment_theme() {
  return array(
    'commerce_payment_transaction' => array(
      'variables' => array('order' => NULL, 'transaction' => NULL, 'view_mode' => NULL),
    ),
    'commerce_payment_transaction_status_text' => array(
      'variables' => array('text' => NULL, 'transaction_status' => NULL),
    ),
    'commerce_payment_transaction_status_icon' => array(
      'variables' => array('transaction_status' => NULL),
    ),
    'commerce_payment_totals' => array(
      'variables' => array('rows' => array(), 'form' => NULL, 'totals' => array(), 'view' => NULL),
      'path' => drupal_get_path('module', 'commerce_payment') . '/theme',
      'template' => 'commerce-payment-totals',
    ),
  );
}

/**
 * Adds the necessary CSS for the line item summary template.
 */
function template_preprocess_commerce_payment_totals(&$variables) {
  drupal_add_css(drupal_get_path('module', 'commerce_payment') . '/theme/commerce_payment.admin.css');
}

/**
 * Implements hook_modules_enabled().
 */
function commerce_payment_modules_enabled($modules) {
  commerce_payment_methods_reset();
  _commerce_payment_default_rules_reset($modules);
}

/**
 * Resets default Rules if necessary when modules are enabled or disabled.
 *
 * @param $modules
 *   An array of module names that have been enabled or disabled.
 */
function _commerce_payment_default_rules_reset($modules) {
  $reset_default_rules = FALSE;

  // Look for any module defining a new payment method.
  foreach ($modules as $module) {
    if (function_exists($module . '_commerce_payment_method_info')) {
      $reset_default_rules = TRUE;
    }
  }

  // If we found a module defining a new payment method, we need to rebuild the
  // default Rules especially for this module so the default payment method Rule
  // will appear properly for this module.
  if ($reset_default_rules) {
    entity_defaults_rebuild();
    rules_clear_cache(TRUE);
  }
}

/**
 * Implements hook_commerce_checkout_page_info().
 */
function commerce_payment_commerce_checkout_page_info() {
  $checkout_pages = array();

  $checkout_pages['payment'] = array(
    'title' => t('Payment'),
    'help' => t('Use the button below to proceed to the payment server.'),
    'status_cart' => FALSE,
    'locked' => TRUE,
    'buttons' => FALSE,
    'weight' => 20,
  );

  return $checkout_pages;
}

/**
 * Implements hook_commerce_checkout_pane_info().
 */
function commerce_payment_commerce_checkout_pane_info() {
  $checkout_panes = array();

  $checkout_panes['commerce_payment'] = array(
    'title' => t('Payment'),
    'page' => 'review',
    'file' => 'includes/commerce_payment.checkout_pane.inc',
    'base' => 'commerce_payment_pane',
    'weight' => 10,
  );

  $checkout_panes['commerce_payment_redirect'] = array(
    'title' => t('Off-site payment redirect'),
    'page' => 'payment',
    'locked' => TRUE,
    'file' => 'includes/commerce_payment.checkout_pane.inc',
    'base' => 'commerce_payment_redirect_pane',
  );

  return $checkout_panes;
}

/**
 * Moves an order ahead to the next page via an order update and redirect.
 *
 * Redirected payment methods are responsible for calling this method when
 * receiving external notifications of successful payment.
 *
 * @param $order
 *   An order object.
 * @param $log
 *   Optional log message to use when updating the order status in conjunction
 *   with the redirect to the next checkout page.
 */
function commerce_payment_redirect_pane_next_page($order, $log = '') {
  // Load the order status object for the current order.
  $order_status = commerce_order_status_load($order->status);

  if ($order_status['state'] == 'checkout' && $order_status['checkout_page'] == 'payment') {
    $payment_page = commerce_checkout_page_load($order_status['checkout_page']);
    $next_page = $payment_page['next_page'];

    $order = commerce_order_status_update($order, 'checkout_' . $next_page, FALSE, NULL, $log);

    // Inform modules of checkout completion if the next page is Completed.
    if ($next_page == 'complete') {
      commerce_checkout_complete($order);
    }
  }
}

/**
 * Moves an order back to the previous page via an order update and redirect.
 *
 * Redirected payment methods are responsible for calling this method when
 * receiving external notifications of failed payment.
 *
 * @param $order
 *   An order object.
 * @param $log
 *   Optional log message to use when updating the order status in conjunction
 *   with the redirect to the previous checkout page.
 */
function commerce_payment_redirect_pane_previous_page($order, $log = '') {
  // Load the order status object for the current order.
  $order_status = commerce_order_status_load($order->status);

  if ($order_status['state'] == 'checkout' && $order_status['checkout_page'] == 'payment') {
    $payment_page = commerce_checkout_page_load($order_status['checkout_page']);
    $prev_page = $payment_page['prev_page'];

    $order = commerce_order_status_update($order, 'checkout_' . $prev_page, FALSE, NULL, $log);
  }
}

/**
 * Implements hook_commerce_payment_totals_row_info().
 */
function commerce_payment_commerce_payment_totals_row_info($totals, $order) {
  $rows = array();

  if (count($totals) == 0) {
    // Add a row for the remaining balance on the order.
    if ($order) {
      $balance = commerce_payment_order_balance($order, $totals);

      $rows[] = array(
        'data' => array(
          array('data' => t('Order balance'), 'class' => array('label')),
          array('data' => commerce_currency_format($balance['amount'], $balance['currency_code']), 'class' => array('balance')),
        ),
        'class' => array('order-balance'),
        'weight' => 10,
      );
    }
  }
  elseif (count($totals) == 1) {
    // Otherwise if there's only a single currency total...
    $currency_code = key($totals);

    // Add a row for the total amount paid.
    $rows[] = array(
      'data' => array(
        array('data' => t('Total paid'), 'class' => array('label')),
        array('data' => commerce_currency_format($totals[$currency_code], $currency_code), 'class' => array('total')),
      ),
      'class' => array('total-paid'),
      'weight' => 0,
    );

    // Add a row for the remaining balance on the order.
    if ($order) {
      // @todo Fix for when there's a FALSE $balance.
      $balance = commerce_payment_order_balance($order, $totals);

      $rows[] = array(
        'data' => array(
          array('data' => t('Order balance'), 'class' => array('label')),
          array('data' => commerce_currency_format($balance['amount'], $balance['currency_code']), 'class' => array('balance')),
        ),
        'class' => array('order-balance'),
        'weight' => 10,
      );
    }
  }
  else {
    $weight = 0;

    foreach ($totals as $currency_code => $amount) {
      $rows[] = array(
        'data' => array(
          array('data' => t('Total paid (@currency_code)', array('@currency_code' => $currency_code)), 'class' => array('label')),
          array('data' => commerce_currency_format($amount, $currency_code), 'class' => array('total')),
        ),
        'class' => array('total-paid', 'total-' . $currency_code),
        'weight' => $weight++,
      );
    }
  }

  return $rows;
}

/**
 * Implements hook_commerce_payment_transaction_insert().
 *
 * When a new payment transaction is inserted that is already completed, check
 * the order balance and invoke a Rules event if the order is paid in full.
 */
function commerce_payment_commerce_payment_transaction_insert($transaction) {
  // If the inserted transaction was marked as a success and placed against a
  // valid order...
  if ($transaction->status == COMMERCE_PAYMENT_STATUS_SUCCESS &&
    $order = commerce_order_load($transaction->order_id)) {
    // Then check to make sure the event hasn't been invoked for this order.
    if (empty($order->data['commerce_payment_order_paid_in_full_invoked'])) {
      // Check the order balance and invoke the event.
      $balance = commerce_payment_order_balance($order);

      if ($balance['amount'] <= 0) {
        // Invoke the event including a hook of the same name.
        rules_invoke_all('commerce_payment_order_paid_in_full', $order, $transaction);

        // Update the order's data array to indicate this just happened.
        $order->data['commerce_payment_order_paid_in_full_invoked'] = TRUE;

        // Save the updated order.
        commerce_order_save($order);
      }
    }
  }
}

/**
 * Implements hook_commerce_payment_transaction_update().
 *
 * When an existing transaction is updated from an incomplete status to
 * completed, check the order balance and invoke a Rules event if the order is
 * paid in full.
 */
function commerce_payment_commerce_payment_transaction_update($transaction) {
  commerce_payment_commerce_payment_transaction_insert($transaction);
}

/**
 * Implements hook_views_api().
 */
function commerce_payment_views_api() {
  return array(
    'api' => 3,
    'path' => drupal_get_path('module', 'commerce_payment') . '/includes/views',
  );
}

/**
 * Returns an array of payment methods defined by enabled modules.
 *
 * @return
 *   An associative array of payment method objects keyed by the method_id.
 */
function commerce_payment_methods() {
  $payment_methods = &drupal_static(__FUNCTION__);

  // If the payment methods haven't been defined yet, do so now.
  if (!isset($payment_methods)) {
    $payment_methods = array();

    // Build the payment methods array, including module names for the purpose
    // of including files if necessary.
    foreach (module_implements('commerce_payment_method_info') as $module) {
      foreach (module_invoke($module, 'commerce_payment_method_info') as $method_id => $payment_method) {
        $payment_method['method_id'] = $method_id;
        $payment_method['module'] = $module;
        $payment_methods[$method_id] = $payment_method;
      }
    }

    drupal_alter('commerce_payment_method_info', $payment_methods);

    foreach ($payment_methods as $method_id => &$payment_method) {
      $defaults = array(
        'method_id' => $method_id,
        'base' => $method_id,
        'title' => '',
        'description' => '',
        'active' => FALSE,
        'checkout' => TRUE,
        'terminal' => TRUE,
        'offsite' => FALSE,
        'offsite_autoredirect' => FALSE,
        'callbacks' => array(),
        'file' => '',
      );

      $payment_method += $defaults;

      // Default the display title to the title if necessary.  The display title
      // is used in instances where the payment method has an official name used
      // as the title (i.e. PayPal WPS) but a different method of display on
      // selection forms (like some text and a set of images).
      if (empty($payment_method['display_title'])) {
        $payment_method['display_title'] = $payment_method['title'];
      }

      // Default the short title to the title if necessary.  Like the display
      // title, the short title is an alternate way of displaying the title to
      // the user consisting of plain text but with unnecessary information
      // stripped off.  The payment method title might be PayPal WPS as it
      // distinguishes itself from other PayPal payment services, but you would
      // only want to display PayPal to the customer as their means of payment.
      if (empty($payment_methods[$method_id]['short_title'])) {
        $payment_method['short_title'] = $payment_method['title'];
      }

      // Merge in default callbacks.
      foreach (array('settings_form', 'submit_form', 'submit_form_validate', 'submit_form_submit', 'redirect_form', 'redirect_form_back', 'redirect_form_validate', 'redirect_form_submit') as $callback) {
        if (!isset($payment_method['callbacks'][$callback])) {
          $payment_method['callbacks'][$callback] = $payment_method['base'] . '_' . $callback;
        }
      }
    }
  }

  return $payment_methods;
}

/**
 * Resets the cached list of payment methods.
 */
function commerce_payment_methods_reset() {
  $payment_methods = &drupal_static('commerce_payment_methods');
  $payment_methods = NULL;
  entity_info_cache_clear();
}

/**
 * Returns a payment method array.
 *
 * @param $method_id
 *   The ID of the payment method to return.
 *
 * @return
 *   The fully loaded payment method object or FALSE if not found.
 */
function commerce_payment_method_load($method_id) {
  $payment_methods = commerce_payment_methods();
  return isset($payment_methods[$method_id]) ? $payment_methods[$method_id] : FALSE;
}

/**
 * Returns the title of any or all payment methods.
 *
 * @param $title
 *   String indicating which title to return, either 'title', 'display_title',
 *     or 'short_title'.
 * @param $method
 *   Optional parameter specifying the payment method whose title to return.
 *
 * @return
 *   Either an array of all payment method titles keyed by the machine name or a
 *   string containing the title for the specified type. If a type is specified
 *   that does not exist, this function returns FALSE.
 */
function commerce_payment_method_get_title($title = 'title', $method = NULL) {
  $payment_methods = commerce_payment_methods();

  // Return a method title if specified and it exists.
  if (!empty($method)) {
    if (isset($payment_methods[$method])) {
      return $payment_methods[$method][$title];
    }
    else {
      // Return FALSE if it does not exist.
      return FALSE;
    }
  }

  // Otherwise turn the array values into the specified title only.
  foreach ($payment_methods as $key => $value) {
    $payment_methods[$key] = $value[$title];
  }

  return $payment_methods;
}

/**
 * Wraps commerce_payment_method_get_title() for the Entity module.
 */
function commerce_payment_method_options_list() {
  return commerce_payment_method_get_title();
}

/**
 * Returns the specified callback for the given payment method if it exists.
 *
 * @param $payment_method
 *   The payment method object.
 * @param $callback
 *   The callback function to return, one of:
 *   - settings_form
 *   - submit_form
 *   - submit_form_validate
 *   - submit_form_submit
 *   - redirect_form
 *   - redirect_form_back
 *   - redirect_form_validate
 *   - redirect_form_submit
 *
 * @return
 *   A string containing the name of the callback function or FALSE if it could
 *     not be found.
 */
function commerce_payment_method_callback($payment_method, $callback) {
  // Include the payment method file if specified.
  if (!empty($payment_method['file'])) {
    $parts = explode('.', $payment_method['file']);
    module_load_include(array_pop($parts), $payment_method['module'], implode('.', $parts));
  }

  // If the specified callback function exists, return it.
  if (!empty($payment_method['callbacks'][$callback]) &&
      function_exists($payment_method['callbacks'][$callback])) {
    return $payment_method['callbacks'][$callback];
  }

  // Otherwise return FALSE.
  return FALSE;
}

/**
 * Returns a payment method instance ID given a payment method ID and the Rule
 *   containing an enabling action with settings.
 *
 * @param $method_id
 *   The ID of the payment method.
 * @param $rule
 *   The Rules configuration object used to provide settings for the method.
 *
 * @return
 *   A string used as the payment method instance ID.
 */
function commerce_payment_method_instance_id($method_id, $rule) {
  $parts = array($method_id, $rule->name);
  return implode('|', $parts);
}

/**
 * Returns a payment method instance array which includes the settings specific
 * to the context of the instance.
 *
 * @param $instance_id
 *   A payment method instance ID in the form of a pipe delimited string
 *     containing the method_id and the enabling Rule's name.
 *
 * @return
 *   The payment method instance object which is identical to the payment method
 *     object with the addition of the settings array.
 */
function commerce_payment_method_instance_load($instance_id) {
  // Return FALSE if there is no pipe delimeter in the instance ID.
  if (strpos($instance_id, '|') === FALSE) {
    return FALSE;
  }

  // Explode the method key into its component parts.
  list($method_id, $rule_name) = explode('|', $instance_id);

  // Return FALSE if we didn't receive a proper instance ID.
  if (empty($method_id) || empty($rule_name)) {
    return FALSE;
  }

  // First load the payment method and add the instance ID.
  $payment_method = commerce_payment_method_load($method_id);
  $payment_method['instance_id'] = $instance_id;

  // Then load the Rule configuration that enables the method.
  $rule = rules_config_load($rule_name);

  // Return FALSE if it couldn't be loaded.
  if (empty($rule)) {
    return FALSE;
  }

  // Iterate over its actions to find one with the matching element ID and pull
  // its settings into the payment method object.
  $payment_method['settings'] = array();

  foreach ($rule->actions() as $action) {
    if ($action->getElementName() == 'commerce_payment_enable_' . $method_id) {
      if (is_array($action->settings['payment_method']) && !empty($action->settings['payment_method']['settings'])) {
        $payment_method['settings'] = $action->settings['payment_method']['settings'];
      }
    }
  }

  return $payment_method;
}

/**
 * Returns an array of transaction payment status objects for the defined
 *   payment statuses.
 *
 * This function invokes hook_commerce_payment_transaction_status_info() so
 * other payment modules can define statuses if necessary. However, it doesn't
 * allow for altering so that existing payment methods cannot be unset. It still
 * does perform an array merge in such a way that the properties for the three
 * core statuses defined by this module may be overridden if the same keys are
 * used in another module's implementation of the info hook.
 */
function commerce_payment_transaction_statuses() {
  $transaction_statuses = &drupal_static(__FUNCTION__);

  // If the statuses haven't been defined yet, do so now.
  if (!isset($transaction_statuses)) {
    $transaction_statuses = module_invoke_all('commerce_payment_transaction_status_info');

    $transaction_statuses += array(
      COMMERCE_PAYMENT_STATUS_PENDING => array(
        'status' => COMMERCE_PAYMENT_STATUS_PENDING,
        'title' => t('Pending'),
        'icon' => drupal_get_path('module', 'commerce_payment') . '/theme/icon-pending.png',
        'total' => FALSE,
      ),
      COMMERCE_PAYMENT_STATUS_SUCCESS => array(
        'status' => COMMERCE_PAYMENT_STATUS_SUCCESS,
        'title' => t('Success'),
        'icon' => drupal_get_path('module', 'commerce_payment') . '/theme/icon-success.png',
        'total' => TRUE,
      ),
      COMMERCE_PAYMENT_STATUS_FAILURE => array(
        'status' => COMMERCE_PAYMENT_STATUS_FAILURE,
        'title' => t('Failure'),
        'icon' => drupal_get_path('module', 'commerce_payment') . '/theme/icon-failure.png',
        'total' => FALSE,
      ),
    );
  }

  return $transaction_statuses;
}

/**
 * Returns an options list of payment transaction statuses.
 */
function commerce_payment_transaction_status_options_list() {
  // Build an array of payment transaction status options.
  $options = array();

  foreach(commerce_payment_transaction_statuses() as $payment_transaction_status) {
    $options[$payment_transaction_status['status']] = $payment_transaction_status['title'];
  }

  return $options;
}

/**
 * Themes the icon representing a payment transaction status.
 */
function theme_commerce_payment_transaction_status_icon($variables) {
  $transaction_status = $variables['transaction_status'];
  return theme('image', array('path' => $transaction_status['icon'], 'alt' => $transaction_status['title'], 'title' => $transaction_status['title'], 'attributes' => array('class' => drupal_html_class($transaction_status['status']))));
}

/**
 * Themes a text value related to a payment transaction status.
 */
function theme_commerce_payment_transaction_status_text($variables) {
  $transaction_status = $variables['transaction_status'];

  return '<span class="' . drupal_html_class($transaction_status['status']) . '">' . $variables['text'] . '</span>';
}

/**
 * Returns the payment transaction status object for the specified status.
 *
 * @param $status
 *   The transaction status string.
 *
 * @return
 *   An object containing the transaction status information or FALSE if the
 *     requested status is not found.
 */
function commerce_payment_transaction_status_load($status) {
  $transaction_statuses = commerce_payment_transaction_statuses();
  return !empty($transaction_statuses[$status]) ? $transaction_statuses[$status] : FALSE;
}

/**
 * Returns an initialized payment transaction object.
 *
 * @param $method_id
 *   The method_id of the payment method for the transaction.
 *
 * @return
 *   A transaction object with all default fields initialized.
 */
function commerce_payment_transaction_new($method_id = '', $order_id = 0) {
  return entity_get_controller('commerce_payment_transaction')->create(array(
    'payment_method' => $method_id,
    'order_id' => $order_id,
  ));
}

/**
 * Saves a payment transaction.
 *
 * @param $transaction
 *   The full transaction object to save.
 *
 * @return
 *   SAVED_NEW or SAVED_UPDATED depending on the operation performed.
 */
function commerce_payment_transaction_save($transaction) {
  return entity_get_controller('commerce_payment_transaction')->save($transaction);
}

/**
 * Loads a payment transaction by ID.
 */
function commerce_payment_transaction_load($transaction_id) {
  $transactions = commerce_payment_transaction_load_multiple(array($transaction_id), array());
  return $transactions ? reset($transactions) : FALSE;
}

/**
 * Loads multiple payment transaction by ID or based on a set of matching conditions.
 *
 * @see entity_load()
 *
 * @param $transaction_ids
 *   An array of transaction IDs.
 * @param $conditions
 *   An array of conditions on the {commerce_payment_transaction} table in the
 *     form 'field' => $value.
 * @param $reset
 *   Whether to reset the internal transaction loading cache.
 *
 * @return
 *   An array of transaction objects indexed by transaction_id.
 */
function commerce_payment_transaction_load_multiple($transaction_ids = array(), $conditions = array(), $reset = FALSE) {
  return entity_load('commerce_payment_transaction', $transaction_ids, $conditions, $reset);
}

/**
 * Deletes a payment transaction by ID.
 *
 * @param $transaction_id
 *   The ID of the transaction to delete.
 *
 * @return
 *   TRUE on success, FALSE otherwise.
 */
function commerce_payment_transaction_delete($transaction_id) {
  return commerce_payment_transaction_delete_multiple(array($transaction_id));
}

/**
 * Deletes multiple payment transactions by ID.
 *
 * @param $transaction_ids
 *   An array of transaction IDs to delete.
 *
 * @return
 *   TRUE on success, FALSE otherwise.
 */
function commerce_payment_transaction_delete_multiple($transaction_ids) {
  return entity_get_controller('commerce_payment_transaction')->delete($transaction_ids);
}

/**
 * Determines access for a variety of operations on payment transactions.
 *
 * @param $op
 *   The operation being performed, one of view, update, create, or delete.
 * @param $transaction
 *   The payment transaction to check.
 * @param $account
 *   The user account attempting the operation; defaults to the current user.
 *
 * @return
 *   TRUE or FALSE indicating access for the operation.
 */
function commerce_payment_transaction_access($op, $transaction, $account = NULL) {
  if (isset($transaction->order_id)) {
    $order = commerce_order_load($transaction->order_id);
    if (!$order) {
      return FALSE;
    }
  }
  else {
    $order = NULL;
  }

  return commerce_payment_transaction_order_access($op, $order, $account);
}

/**
 * Determines access for a variety of operations for payment transactions on a given order.
 *
 * @param $op
 *   The payment transaction operation being performed, one of view, update, create, or delete.
 * @param $order
 *   The order to check against (optional if $op == 'create').
 * @param $account
 *   The user account attempting the operation; defaults to the current user.
 *
 * @return
 *   TRUE or FALSE indicating access for the operation.
 */
function commerce_payment_transaction_order_access($op, $order, $account = NULL) {
  global $user;

  if (empty($account)) {
    $account = clone($user);
  }

  // Grant administrators access to do anything.
  if (user_access('administer payments', $account)) {
    return TRUE;
  }

  switch ($op) {
    // Creating new payment transactions.
    case 'create':
      if (user_access('create payments', $account)) {
        // We currently allow any user to create any payment transaction,
        // regardless of the order, because entity_access() doesn't give us a
        // way to discriminate on the order.
        // @todo: find a way to prevent creating a payment transaction if the
        // user doesn't have access to the order.
        if (!isset($order) || commerce_order_access('update', $order, $account)) {
          return TRUE;
        }
      }
      break;

    // Viewing payment transactions.
    case 'view':
      if (user_access('view payments', $account)) {
        if (commerce_order_access('view', $order, $account)) {
          return TRUE;
        }
      }
      break;

    case 'update':
      if (user_access('update payments', $account)) {
        if (commerce_order_access('view', $order, $account)) {
          return TRUE;
        }
      }
      break;

    case 'delete':
      if (user_access('delete payments', $account)) {
        if (commerce_order_access('update', $order, $account)) {
          return TRUE;
        }
      }
      break;
  }

  return FALSE;
}

/**
 * Implements hook_query_TAG_alter().
 *
 * Implement access control on payment transaction. This is different from other
 * entities because the access to a payment transaction is partially delegated
 * to its order.
 */
function commerce_payment_query_commerce_payment_transaction_access_alter(QueryAlterableInterface $query) {
  // Read the meta-data from the query.
  if (!$account = $query->getMetaData('account')) {
    global $user;
    $account = $user;
  }

  // If the user has the administration permission, nothing to do.
  if (user_access('administer payments', $account)) {
    return;
  }

  // Join the payment transaction to their orders.
  if (user_access('view payments', $account)) {
    $tables = &$query->getTables();

    // Look for an existing commerce_order table.
    foreach ($tables as $table) {
      if ($table['table'] === 'commerce_order') {
        $order_alias = $table['alias'];
        break;
      }
    }

    // If not found, attempt a join against the first table.
    if (!isset($order_alias)) {
      reset($tables);
      $base_table = key($tables);
      $order_alias = $query->innerJoin('commerce_order', 'co', '%alias.order_id = ' . $base_table . '.order_id');
    }

    // Perform the access control on the order.
    commerce_entity_access_query_alter($query, 'commerce_order', $order_alias);
  }
  else {
    // The user has access to no payment transaction.
    $query->where('1 = 0');
  }
}

/**
 * Calculates the balance of an order by subtracting the total of all successful
 *   transactions from the total of all the line items on the order.
 *
 * @param $order
 *   The fully loaded order object whose balance should be calculated.
 * @param $totals
 *   Optionally submit an array of transaction totals keyed by currency code
 *     with the amount as the value.
 *
 * @return
 *   An array containing the amount and currency code representing the balance
 *     of the order or FALSE if it is impossible to calculate.
 */
function commerce_payment_order_balance($order, $totals = array()) {
  $wrapper = entity_metadata_wrapper('commerce_order', $order);
  $order_total = $wrapper->commerce_order_total->value();

  // Calculate the transaction totals if not supplied.
  if (empty($totals)) {
    $transaction_statuses = commerce_payment_transaction_statuses();

    foreach (commerce_payment_transaction_load_multiple(array(), array('order_id' => $order->order_id)) as $transaction) {
      // If the payment transaction status indicates it should include the
      // current transaction in the total...
      if ($transaction_statuses[$transaction->status]['total']) {
        // Add the transaction to its currency's running total if it exists...
        if (isset($totals[$transaction->currency_code])) {
          $totals[$transaction->currency_code] += $transaction->amount;
        }
        else {
          // Or begin a new running total for the currency.
          $totals[$transaction->currency_code] = $transaction->amount;
        }
      }
    }
  }

  // Only return a balance if the totals array contains a single matching currency.
  if (count($totals) == 1 && isset($totals[$order_total['currency_code']])) {
    return array('amount' => $order_total['amount'] - $totals[$order_total['currency_code']], 'currency_code' => $order_total['currency_code']);
  }
  elseif (empty($totals)) {
    return array('amount' => $order_total['amount'], 'currency_code' => $order_total['currency_code']);
  }
  else {
    return FALSE;
  }
}

/**
 * Returns a sorted array of payment totals table rows.
 *
 * @param $totals
 *   An array of payment totals whose keys are currency codes and values are the
 *     total amount paid in each currency.
 * @param $order
 *   If available, the order object to which the payments apply.
 *
 * @return
 *   An array of table row data as expected by theme_table().
 *
 * @see hook_commerce_payment_totals_row_info()
 */
function commerce_payment_totals_rows($totals, $order) {
  // Retrieve rows defined by the hook and allow other modules to alter them.
  $rows = module_invoke_all('commerce_payment_totals_row_info', $totals, $order);
  drupal_alter('commerce_payment_totals_row_info', $rows, $totals, $order);

  // Sort the rows by weight and return the array.
  uasort($rows, 'drupal_sort_weight');

  return $rows;
}

/**
 * Callback for getting payment transaction properties.
 *
 * @see commerce_payment_entity_property_info()
 */
function commerce_payment_transaction_get_properties($transaction, array $options, $name) {
  switch ($name) {
    case 'user':
      return $transaction->uid;
    case 'order':
      return !empty($transaction->order_id) ? $transaction->order_id : commerce_order_new();
    case 'message':
      if ($transaction->message) {
        return t($transaction->message, is_array($transaction->message_variables) ? $transaction->message_variables : array());
      }
      else {
        return '';
      }
  }
}

/**
 * Callback for setting payment transaction properties.
 *
 * @see commerce_payment_entity_property_info()
 */
function commerce_payment_transaction_set_properties($transaction, $name, $value) {
  switch ($name) {
    case 'user':
      $transaction->uid = $value;
      break;
    case 'order':
      $transaction->order_id = $value;
      break;
  }
}