ubercart/ca/ca.module

<?php
// $Id$

/**
 * @file
 * This is a demonstration module for the new conditional actions API.
 */

require_once('ca.inc');

/*******************************************************************************
 * Drupal Hooks
 ******************************************************************************/

/**
 * Implementation of hook_menu().
 */
function ca_menu() {
  $items['admin/settings/ca'] = array(
    'title' => 'Conditional actions',
    'description' => 'Administer the predicates setup to automate your store.',
    'page callback' => 'ca_admin',
    'access arguments' => array('administer conditional actions'),
    'file' => 'ca.admin.inc',
  );
  $items['admin/settings/ca/overview'] = array(
    'title' => 'Overview',
    'weight' => 0,
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['admin/settings/ca/add'] = array(
    'title' => 'Add a predicate',
    'description' => 'Allows an administrator to create a new predicate.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('ca_predicate_meta_form', '0'),
    'access arguments' => array('administer conditional actions'),
    'weight' => 5,
    'file' => 'ca.admin.inc',
    'type' => MENU_LOCAL_TASK,
  );
  $items['admin/settings/ca/%/edit'] = array(
    'title' => 'Edit predicate meta data',
    'description' => 'Edit the meta data for a predicate like title, trigger, etc.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('ca_predicate_meta_form', 3),
    'access arguments' => array('administer conditional actions'),
    'file' => 'ca.admin.inc',
    'type' => MENU_CALLBACK,
  );
  $items['admin/settings/ca/%/reset'] = array(
    'title' => t('Reset a predicate'),
    'page callback' => 'drupal_get_form',
    'page arguments' => array('ca_predicate_delete_form', 3),
    'access arguments' => array('administer conditional actions'),
    'file' => 'ca.admin.inc',
    'type' => MENU_CALLBACK,
  );
  $items['admin/settings/ca/%/delete'] = array(
    'title' => 'Delete a predicate',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('ca_predicate_delete_form', 3),
    'access arguments' => array('administer conditional actions'),
    'file' => 'ca.admin.inc',
    'type' => MENU_CALLBACK,
  );
  $items['admin/settings/ca/%/conditions'] = array(
    'title' => 'Edit predicate conditions',
    'description' => "Edit a predicate's conditions.",
    'page callback' => 'drupal_get_form',
    'page arguments' => array('ca_predicate_meta_form', 3),
    'access arguments' => array('administer conditional actions'),
    'file' => 'ca.admin.inc',
    'type' => MENU_CALLBACK,
  );

  return $items;
}

/**
 * Implementation of hook_perm().
 */
function ca_perm() {
  return array('administer conditional actions');
}

/*******************************************************************************
 * Conditional Actions Hooks
 ******************************************************************************/

function ca_ca_entity() {
  $entities = array();

  $entities['user'] = array(
    '#title' => t('Drupal user'),
    '#type' => 'object',
    '#load' => 'user_load',
    '#save' => 'user_save',
  );

  return $entities;
}

/**
 * Implementation of hook_ca_action().
 */
function ca_ca_action() {
  $actions['ca_drupal_set_message'] = array(
    '#title' => t('Display a message to the user'),
    '#category' => t('Drupal'),
    '#callback' => 'ca_action_drupal_set_message',
    '#arguments' => array(),
  );

  return $actions;
}

/**
 * Implementation of hook_ca_predicate().
 */
function ca_ca_predicate() {
  $predicates = array();

  $predicates['complain_payment_not_enough'] = array(
    '#title' => t('Ask for more money.'),
    '#description' => t('Displays a message when a payment is recieved, but the total is > $0.00.'),
    '#class' => 'payment',
    '#status' => 0,
    '#trigger' => 'uc_payment_entered',
    '#conditions' => array(
      '#operator' => 'AND',
      '#conditions' => array(
        array(
          '#name' => 'uc_order_balance',
          '#title' => 'If the balance is greater than $0.00.',
          '#argument_map' => array(
            'order' => 'order',
          ),
          '#settings' => array(
            'negate' => FALSE,
            'balance_comparison' => 'greater',
          ),
        ),
        array(
          '#name' => 'uc_order_status',
          '#title' => 'If the order status is not already Payment Received.',
          '#argument_map' => array(
            'order' => 'order',
          ),
          '#settings' => array(
            'negate' => TRUE,
            'order_status' => 'payment_received',
          ),
        ),
        array(
          '#operator' => 'OR',
          '#conditions' => array(
            array(
              '#name' => 'uc_order_payment_method',
              '#title' => 'If the payment method is not Check.',
              '#argument_map' => array(
                'order' => 'order',
              ),
              '#settings' => array(
                'negate' => FALSE,
                'payment_method' => 'check',
              ),
            ),
            array(
              '#name' => 'uc_order_payment_method',
              '#title' => 'If the payment method is not COD.',
              '#argument_map' => array(
                'order' => 'order',
              ),
              '#settings' => array(
                'negate' => FALSE,
                'payment_method' => 'cod',
              ),
            ),
          ),
        ),
      ),
    ),
    '#actions' => array(
      array(
        '#name' => 'ca_drupal_set_message',
        '#title' => 'Ask the customer to pay more money.',
        '#settings' => array(
          'message_type' => 'status',
          'message_text' => 'Pay more money, yo!',
        ),
      ),
    ),
  );

  return $predicates;
}


/*******************************************************************************
 * Module and Helper Functions
 ******************************************************************************/

/**
 * Pulls a trigger and evaluates any predicates associated with that trigger.
 *
 * @param ...
 *   Accepts a variable number of arguments.  The first should always be the
 *     string name of the trigger to pull with any additional arguments being
 *     the arguments expected by the trigger and used for evaluation.
 * @return
 *   TRUE or FALSE indicating if at least one predicate was evaluated.
 */
function ca_pull_trigger() {
  $args = func_get_args();
  $trigger = array_shift($args);

  // Load all the triggers.
  $triggers = module_invoke_all('ca_trigger');

  // Fail if the specified trigger doesn't exist.
  if (!is_array($triggers[$trigger])) {
    return FALSE;
  }

  // Load any predicates associated with the trigger.
  $predicates = ca_load_trigger_predicates($trigger);

  // Fail if we didn't find any predicates.
  if (!$predicates || count($predicates) == 0) {
    return FALSE;
  }

  // Prepare the arguments for evaluation.
  $arguments = ca_parse_trigger_args($triggers[$trigger], $args);

  // Fail if we didn't receive the right type of or enough arguments.
  if (!$arguments) {
    return FALSE;
  }

  // Loop through the predicates and evaluate them one by one.
  foreach ($predicates as $pid => $predicate) {
    // If all of a predicate's conditions evaluate to TRUE...
    if (ca_evaluate_conditions($predicate, $arguments)) {
      // Then perform its actions.
      ca_perform_actions($predicate, $arguments);
    }
  }

  return TRUE;
}

/**
 * Parses the argument array into a CA friendly array for the trigger.
 *
 * @param $trigger
 *   The name of the trigger for which we are parsing the arguments.
 * @param $args
 *   An array of arguments to check against the expected arguments.
 * @return
 *   The array of arguments keyed according to the trigger's argument names.
 */
function ca_parse_trigger_args($trigger, $args) {
  // Fail if we didn't receive enough arguments for this trigger.
  if (count($args) < count($trigger['#arguments'])) {
    return FALSE;
  }

  // Load all the entity information.
  $entities = module_invoke_all('ca_entity');

  // Loop through the expected arguments.
  foreach ($trigger['#arguments'] as $key => $value) {
    // Grab for comparison the next argument passed to the trigger.
    $arg = array_shift($args);

    // Check the type and fail if it is incorrect.
    if (gettype($arg) != $entities[$value['#entity']]['#type']) {
      return FALSE;
    }

    // Add the entity to the arguments array along with its meta data.
    $arguments[$key] = array(
      '#entity' => $value['#entity'],
      '#title' => $value['#title'],
      '#data' => $arg,
    );
  }

  return $arguments;
}

/**
 * Loads predicates based on the specified parameters.
 *
 * @param $trigger
 *   The name of the trigger for which to search when loading the predicates.
 * @param $all
 *   FALSE by default, specifies whether we want to load all possible predicates
 *     or only those that are active (status > 0).
 * @return
 *   An array of predicates.
 */
function ca_load_trigger_predicates($trigger, $all = FALSE) {
  // Trigger actions can pull other triggers. Lock predicates when they are
  // marked for evaluation so they can't be evaluated again.
  static $locked = array();

  // Load all the module defined predicates.
  $predicates = module_invoke_all('ca_predicate');

  // Loop through the module defined predicates to prepare the data - unsets
  // inactive predicates if $all == FALSE and adds a default weight if need be.
  foreach ($predicates as $key => $value) {
    // Unset the predicate if it doesn't use the specified trigger.
    if ($value['#trigger'] != $trigger) {
      unset($predicates[$key]);
      continue;
    }

    if (!$all && $value['#status'] <= 0) {
      unset($predicates[$key]);
    }
    else {
      // Prevent predicates from being evaluated more than once in a page load.
      if (in_array($key, $locked)) {
        unset($predicates[$key]);
      }
      else {
        $locked[$key] = $key;
      }

      if (!isset($value['#weight'])) {
        $predicates[$key]['#weight'] = 0;
      }
    }
  }

  // Load and loop through the predicates from the database for this trigger.
  $result = db_query("SELECT * FROM {ca_predicates} WHERE ca_trigger = '%s'", $trigger);
  while ($data = db_fetch_array($result)) {
    // Module defined predicates have string IDs.  When a user modifies one of
    // these, we unset the module defined predicate and reconsider adding it in.
    if (!is_numeric($data['pid'])) {
      unset($predicates[$data['pid']]);
    }

    // Add predicates from the database to our return array if $all == TRUE or
    // if the predicate is active.
    if ($all || $data['status'] > 0) {
      // Prevent predicates from being evaluated more than once in a page load.
      if (!in_array($data['pid'], $locked)) {
        $predicates[$data['pid']] = ca_prepare_db_predicate($data);
        $locked[$key] = $data['pid'];
      }
    }
  }

  uasort($predicates, 'ca_weight_sort');

  return $predicates;
}

/**
 * Prepares predicate data from the database into a full predicate array.
 *
 * @param $data
 *   An array of data representing a row in the predicates table.
 * @return
 *   A predicate array.
 */
function ca_prepare_db_predicate($data) {
  $predicate = array();

  foreach ($data as $key => $value) {
    switch ($key) {
      // Condition and action data needs to be unserialized.
      case 'conditions':
      case 'actions':
        $predicate['#'. $key] = unserialize($value);
        break;
      case 'ca_trigger':
        $predicate['#trigger'] = $value;
        break;
      default:
        $predicate['#'. $key] = $value;
        break;
    }
  }

  return $predicate;
}

/**
 * Evaluates a predicate's conditions.
 *
 * @param $predicate
 *   A fully loaded predicate array.
 * @param $arguments
 *   The array of parsed arguments for the trigger.
 * @return
 *   TRUE or FALSE indicating the success or failure of the evaluation.
 */
function ca_evaluate_conditions($predicate, $arguments) {
  // Automatically pass if there are no conditions.
  if (count($predicate['#conditions']) == 0) {
    return TRUE;
  }

  // Load the data for the conditions as defined by modules.
  $condition_data = module_invoke_all('ca_condition');

  // Recurse through the predicate's conditions for evaluation.
  $result = _ca_evaluate_conditions_tree($predicate['#conditions'], $arguments, $condition_data);

  if (is_null($result)) {
    $result = FALSE;
  }

  return $result;
}

function _ca_evaluate_conditions_tree($condition, $arguments, $condition_data) {
  if (isset($condition['#operator']) && is_array($condition['#conditions'])) {
    foreach ($condition['#conditions'] as $sub_condition) {
      $result = _ca_evaluate_conditions_tree($sub_condition, $arguments, $condition_data);

      // Invalid conditions return NULL. Skip it and go to the next one.
      if (is_null($result)) {
        continue;
      }
      // Save the processors! Apply Boolean shortcutting if we can.
      if ($condition['#operator'] == 'OR' && $result) {
        return TRUE;
      }
      else if ($condition['#operator'] == 'AND' && !$result) {
        return FALSE;
      }
    }
    return $result;
  }
  else {
    return _ca_evaluate_condition($condition, $arguments, $condition_data);
  }
}

function _ca_evaluate_condition($condition, $arguments, $condition_data) {
  $args = array();

  // Make sure the condition tree is sane.
  if (!is_array($condition_data[$condition['#name']])) {
    return NULL;
  }

  // Get the callback function for the current condition.
  $callback = $condition_data[$condition['#name']]['#callback'];

  // Skip this condition if the function does not exist.
  if (!function_exists($callback)) {
    return NULL;
  }

  // Loop through the expected arguments for a condition.
  foreach ($condition_data[$condition['#name']]['#arguments'] as $key => $value) {
    // Using the argument map for the condition on this predicate, fetch the
    // argument that was passed to the trigger that matches to the argument
    // needed to evaluate this condition.
    if (isset($condition['#argument_map'][$key])) {
      $args[] = $arguments[$condition['#argument_map'][$key]]['#data'];
    }
    else {
      // Skip this condition of the predicate didn't map the arguments needed.
      return NULL;
    }
  }

  // Add the condition settings to the argument list.
  $args[] = $condition['#settings'];

  // Call the condition's function with the appropriate arguments.
  $result = call_user_func_array($callback, $args);

  // If the negate operator is TRUE, then switch the result!
  if ($condition['#settings']['negate']) {

    $result = !$result;
  }
  return $result;
}

/**
 * Performs a predicate's actions in order, preserving changes to the arguments.
 *
 * @param $predicate
 *   A fully loaded predicate array.
 * @param $arguments
 *   The array of parsed arguments for the trigger.
 */
function ca_perform_actions($predicate, $arguments) {
  // Exit now if we don't have any actions.
  if (count($predicate['#actions']) == 0) {
    return;
  }

  // Set the actions' weight if necessary and sort actions by their weight.
  for ($i = 0; $i < count($predicate['#actions']); $i++) {
    if (!isset($predicate['#actions'][$i]['#weight'])) {
      $predicate['#actions'][$i]['#weight'] = 0;
    }
  }
  usort($predicate['#actions'], 'ca_weight_sort');

  // Load the data for the actions as defined by modules.
  $action_data = module_invoke_all('ca_action');

  foreach ($predicate['#actions'] as $action) {
    $args = array();

    // Get the callback function for the current action.
    $callback = $action_data[$action['#name']]['#callback'];

    // Do not perform the action if the function does not exist.
    if (!function_exists($callback)) {
      continue;
    }

    // Loop through the expected arguments for a condition.
    foreach ($action_data[$action['#name']]['#arguments'] as $key => $value) {
      // Using the argument map for the action on this predicate, fetch the
      // argument that was passed to the trigger that matches to the argument
      // needed to perform this action.
      if (isset($action['#argument_map'][$key])) {
        // Adding the arguments as references so action functions can update the
        // arguments here when they make changes to the argument data.
        $args[] = &$arguments[$action['#argument_map'][$key]]['#data'];
      }
      else {
        // Skip this action of the predicate didn't map the arguments needed.
        continue 2;
      }
    }

    // Add the condition settings to the argument list.
    $args[] = $action['#settings'];

    // Call the action's function with the appropriate arguments.
    call_user_func_array($callback, $args);
  }
}

/**
 * Loads a predicate by its ID.
 *
 * @param $pid
 *   The ID of the predicate to load.
 * @return
 *   A fully loaded predicate array.
 */
function ca_load_predicate($pid) {
  $predicate = array();

  // First attempt to load the predicate from the database.
  $result = db_query("SELECT * FROM {ca_predicates} WHERE pid = '%s'", $pid);
  if ($predicate = db_fetch_array($result)) {
    $predicate = ca_prepare_db_predicate($predicate);
  }
  else {
    // Otherwise look for it in the module defined predicates.
    $predicates = module_invoke_all('ca_predicate');

    if (!empty($predicates[$pid])) {
      $predicate = $predicates[$pid];
    }
  }

  return $predicate;
}

/**
 * Saves a predicate array to the database.
 *
 * @param $predicate
 *   A fully loaded predicate array.
 */
function ca_save_predicate($predicate) {
  // Check to see if the predicate has been previously saved to the database.
  $result = db_result(db_query("SELECT COUNT(*) FROM {ca_predicates} WHERE pid = '%s'", $predicate['#pid']));

  if (!$result) {
    // If not, then insert it.
    db_query("INSERT INTO {ca_predicates} (pid, title, description, class, status, weight, uid, ca_trigger, conditions, actions, created, modified) VALUES ('%s', '%s', '%s', '%s', %d, %d, %d, '%s', '%s', '%s', %d, %d)",
      $predicate['#pid'], $predicate['#title'], $predicate['#description'], $predicate['#class'], $predicate['#status'], $predicate['#weight'], $predicate['#uid'], $predicate['#trigger'], serialize($predicate['#conditions']), serialize($predicate['#actions']), time(), time());
  }
  else {
    // Otherwise, update it.
    db_query("UPDATE {ca_predicates} SET title = '%s', description = '%s', class = '%s', status = %d, weight = %d, uid = %d, ca_trigger = '%s', conditions = '%s', actions = '%s', modified = %d WHERE pid = '%s'",
      $predicate['#title'], $predicate['#description'], $predicate['#class'], $predicate['#status'], $predicate['#weight'], $predicate['#uid'], $predicate['#trigger'], serialize($predicate['#conditions']), serialize($predicate['#actions']), time(), $predicate['#pid']);
  }
}

/**
 * Deletes a predicate from the database.
 *
 * @param $pid
 *   The ID of the predicate to delete.
 */
function ca_delete_predicate($pid) {
  db_query("DELETE FROM {ca_predicates} WHERE pid = '%s'", $pid);
}

// Compares two conditional action arrays to sort them by #weight.
function ca_weight_sort($a, $b) {
  if ($a['#weight'] == $b['#weight']) {
    return 0;
  }

  return ($a['#weight'] > $b['#weight']) ? 1 : -1;
}

function _ca_convert_configurations() {
  global $user;

  if (db_table_exists('workflow_ng_cfgs')) {
    $result = db_query("SELECT name, data FROM {workflow_ng_cfgs} WHERE altered = 1");
    $predicates = array();
    while ($configuration_row = db_fetch_object($result)) {
      $predicate = array('#pid' => $configuration_row->name);
      $conditions = array();
      $actions = array();
      if ($configuration = unserialize($configuration_row->data)) {
        $predicate['#class'] = $configuration['#module'];
        $predicate['#title'] = $configuration['#label'];
        switch ($configuration['#event']) {
          case 'order_status_update':
            $trigger = 'uc_order_status_update';
          break;
          case 'payment_entered':
            $trigger = 'uc_payment_entered';
          break;
          case 'checkout_complete':
            $trigger = 'uc_checkout_complete';
          break;
          default:
            $trigger = $configuration['#event'];
          break;
        }
        $predicate['#trigger'] = $trigger;
        $predicate['#weight'] = $configuration['#weight'];
        $predicate['#status'] = $configuration['#active'];
        for ($i = 0; isset($configuration[$i]); $i++) {
          if ($configuration[$i]['#type'] == 'action') {
            $action = $configuration[$i];
            if (isset($action[$i]['#label'])) {
              $action['#title'] = $action['#label'];
              unset($action['#label']);
            }
            else {
              $action['#title'] = $action['#name'];
            }
            $actions[] = $action;
          }
          else {
            $condition = _ca_convert_conditions($configuration[$i]);
            if ($condition) {
              $conditions[] = $condition;
            }
          }
        }
        if ($conditions) {
          $predicate['#conditions'] = array(
            '#operator' => 'AND',
            '#conditions' => $conditions,
          );
        }
        $predicate['#uid'] = $user->uid;
        ca_save_predicate($predicate);
      }
    }
  }
}

function _ca_convert_conditions($condition_tree) {
  $ca_condition = array();

  if ($condition_tree['#type'] == 'AND' || $condition_tree['#type'] == 'OR') {
    $ca_condition['#operator'] = $condition_tree['#type'];
    $ca_condition['#conditions'] = array();
    for ($i = 0; isset($condition_tree[$i]); $i++) {
      $condition = _ca_convert_conditions($condition_tree[$i]);
      if ($condition) {
        $ca_condition['#conditions'][] = $condition;
      }
    }
  }
  else if ($condition_tree['#type'] == 'condition') {
    $ca_condition['#name'] = $condition_tree['#name'];
    $ca_condition['#title'] = $condition_tree['#label'];
    $ca_condition['#argument_map'] = $condition_tree['#argument map'];
    $ca_condition['#settings'] = $condition_tree['#settings'];
    if (isset($condition_tree['#negate'])) {
      $ca_condition['#settings']['negate'] = $condition_tree['#negate'];
    }
  }

  return $ca_condition;
}
