function userpoints_userpointsapi in User Points 5.3

Same name and namespace in other branches

1. 5 userpoints.module \userpoints_userpointsapi()
2. 5.2 userpoints.module \userpoints_userpointsapi()
3. 6 userpoints.module \userpoints_userpointsapi()
4. 7 userpoints.module \userpoints_userpointsapi()

Parameters

$params(array) or (int): if (int) assumed to be points for current user Accepts an array of keyed variables and parameters 'points' => # of points (int) (required) 'moderate' => TRUE/FALSE 'uid' => $user->uid 'operation' => 'published' 'moderated' etc. 'tid' => 'category ID' 'expirydate' => timestamp or 0, 0 = non-expiring; NULL = site default 'description' => 'description' 'reference' => reserved for module specific use 'display' => whether or not to display "points awarded" message 'txn_id' => Transaction ID of points, If present an UPDATE is performed 'entity_id' => ID of an entity in the Database. ex. $node->id or $user->uid 'entity_type' => string of the entity type. ex. 'node' or 'user' NOT 'node-content-custom'

Return value

array with status and reason. 'status' => FALSE when no action is take, TRUE when points are credited or debited 'reason' => (string) error message to indicate reason for failure

7 calls to userpoints_userpointsapi()

userpoints_action_grant_points in ./userpoints_workflow_ng.module

Implementation of a workflow-ng action: grant points to a user

userpoints_admin_txn_submit in ./userpoints.module

userpoints_comment in ./userpoints_basic.module

userpoints_confirm_approve_submit in ./userpoints.module

userpoints_expire_transactions in ./userpoints.module

... See full list

File

./userpoints.module, line 435

Code

function userpoints_userpointsapi($params) {

  //Test for the existence of parameters and set defaults if necessary
  if (!isset($params['txn_id'])) {

    //If a txn_id is passed in we'll do an UPDATE thus the std check don't apply
    if (is_numeric($params)) {
      $points = $params;
      $params = array();
      $params['points'] = $points;
      unset($points);
    }
    if (!is_array($params)) {

      //has to be an array to continue
      return array(
        'status' => false,
        'reason' => 'Parameters did not properly form as an array,
                     this is an internal module error.
                    ',
      );
    }
    if (!isset($params['uid'])) {
      global $user;
      $params['uid'] = $user->uid;
    }
    if (!isset($params['operation'])) {
      $params['operation'] = NULL;
    }
    if (!isset($params['description'])) {
      $params['description'] = NULL;
    }
    if (!isset($params['reference'])) {
      $params['reference'] = NULL;
    }
    if (!isset($params['display'])) {
      $params['display'] = NULL;
    }
    if (!isset($params['moderate'])) {

      //if not passed then site default is used
      $params['status'] = variable_get(USERPOINTS_POINTS_MODERATION, 0);
    }
    else {
      if ($params['moderate'] == true) {
        $params['status'] = 1;
      }
      else {
        $params['status'] = 0;
      }
    }
    if (!isset($params['tid']) || !is_numeric($params['tid'])) {

      //if not passed then site default is used
      $params['tid'] = variable_get(USERPOINTS_CATEGORY_DEFAULT_TID, NULL);
    }
    if (!isset($params['entity_id'])) {
      $params['entity_id'] = NULL;
    }
    if (!isset($params['entity_type'])) {
      $params['entity_type'] = NULL;
    }

    // anonymous users do not get points, and there have to be points to process
    if ($params['uid'] == 0 || $params['points'] == 0) {
      return array(
        'status' => false,
        'reason' => 'uid or points = 0. Anonymous users do not get points
                     and there must be points to process.
                    ',
      );
    }
  }
  else {

    //We have a txn_id so we can look up some user information
    $sql = "SELECT uid from {userpoints_txn} WHERE txn_id = %d";
    $params['uid'] = db_result(db_query($sql, $params['txn_id']));
  }

  //if txn_id

  // Load the user object that will be awarded the points
  $account = user_load(array(
    'uid' => $params['uid'],
  ));

  // Call the _userpoints hook, and stop if one of them returns FALSE
  $rc = module_invoke_all('userpoints', 'points before', $params['points'], $account->uid, $params['operation']);
  foreach ($rc as $key => $value) {
    if ($value == FALSE) {

      // Do not process the points
      return array(
        'status' => false,
        'reason' => t('%key returned false from the hook_userpoints points before call', array(
          '%key' => $key,
        )),
      );
    }
  }
  if ($params['points'] < 0) {
    $msg = t('lost');
  }
  elseif ($params['status'] == 2) {

    //points have been declined
    $msg = t('was declined');
  }
  else {
    $msg = t('earned');
  }
  $ret = _userpoints_transaction($params);
  if ($ret == false) {
    return array(
      'status' => false,
      'reason' => 'transaction failed in _userpoints_transaction, this is an internal module error',
    );
  }
  if ($params['status'] == 1) {
    $mesg = t('User %uname %op %points, pending adminstrator approval', array_merge(userpoints_translation(), array(
      '%uname' => $account->name,
      '%op' => $msg,
      '%points' => t(format_plural(abs($params['points']), '1 !point', '@count !points'), userpoints_translation()),
    )));
  }
  else {
    $mesg = t('User !uname !op !points Total now is !total.', array_merge(array(
      '!uname' => $account->name,
      '!op' => $msg,
      '!points' => t(format_plural(abs($params['points']), '1 !point', '@count !points'), userpoints_translation()),
      '!total' => t(format_plural(userpoints_get_current_points($params['uid'], $params['tid']), '1 !point', '@count !points'), userpoints_translation()),
    )));
  }

  //if $params['status']
  if ($mesg && ($params['display'] || $params['display'] === null && variable_get(USERPOINTS_DISPLAY_MESSAGE, 1) == 1)) {
    drupal_set_message($mesg);
  }

  // Call the _userpoints hook to allow modules to act after points are awarded
  module_invoke_all('userpoints', 'points after', $params['points'], $account->uid, $params['operation']);
  return array(
    'status' => true,
  );
}