function userpoints_userpointsapi in User Points 6

Same name and namespace in other branches

1. 5.3 userpoints.module \userpoints_userpointsapi()
2. 5 userpoints.module \userpoints_userpointsapi()
3. 5.2 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 'time_stamp' => unix time of the points assignement date '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

9 calls to userpoints_userpointsapi()

UserpointsTestCase::testBasicCall in tests/userpoints_api.test

UserpointsTestCase::testExpiration in tests/userpoints_api.test

UserpointsTestCase::testModeration in tests/userpoints_api.test

UserpointsTestCase::testParamsArrayCall in tests/userpoints_api.test

userpoints_action_grant_points in ./userpoints_rules.rules.inc

Rules action - grant points to a user.

... See full list

File

./userpoints.module, line 584

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 checks 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;
    }

    // check if parameters are set
    $params_null_check = array(
      'operation',
      'description',
      'reference',
      'display',
      'entity_id',
      'entity_type',
    );
    foreach ($params_null_check as $param_null_check) {
      if (!isset($params[$param_null_check])) {
        $params[$param_null_check] = NULL;
      }
    }
    if (!isset($params['moderate'])) {

      // If not passed then site default is used.
      $params['status'] = variable_get(USERPOINTS_POINTS_MODERATION, USERPOINTS_TXN_STATUS_APPROVED);
    }
    else {
      $params['status'] = $params['moderate'] ? USERPOINTS_TXN_STATUS_PENDING : USERPOINTS_TXN_STATUS_APPROVED;
    }
    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);
    }

    // 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
    $params['uid'] = db_result(db_query('SELECT uid from {userpoints_txn} WHERE txn_id = %d', $params['txn_id']));
  }

  //if txn_id

  // Load the user object that will be awarded the points
  $name = db_result(db_query('SELECT name FROM {users} WHERE uid = %d', $params['uid']));
  if ($name == '') {
    return array(
      'status' => FALSE,
      'reason' => 'invalid uid or user account could not be loaded',
    );
  }

  // Call the _userpoints hook, and stop if one of them returns FALSE
  $rc = module_invoke_all('userpoints', 'points before', $params);
  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 (isset($params['points']) && $params['points'] < 0) {
    $msg = t('lost');
  }
  elseif (isset($params['status']) && $params['status'] == USERPOINTS_TXN_STATUS_DECLINED) {

    //points have been declined
    $msg = t('was declined');
  }
  elseif (!empty($params['expired'])) {
    $msg = t('expired');
  }
  else {
    $msg = t('earned');
  }
  $ret = _userpoints_transaction($params);

  // Reset the static cache of userpoints.
  userpoints_get_current_points(NULL, NULL, TRUE);
  if ($ret == FALSE) {
    return array(
      'status' => FALSE,
      'reason' => 'transaction failed in _userpoints_transaction, this is an internal module error',
    );
  }
  if ($params['status'] == USERPOINTS_TXN_STATUS_PENDING) {
    $mesg = t('User %uname %op %pointsvalue !points, pending administrator approval.', array_merge(userpoints_translation(), array(
      '%uname' => $name,
      '%op' => $msg,
      '%pointsvalue' => abs($params['points']),
      '%total' => userpoints_get_current_points($params['uid'], $params['tid']),
    )));
  }
  else {
    $mesg = t('User %uname %op %pointsvalue !points Total now is %total !points.', array_merge(userpoints_translation(), array(
      '%uname' => $name,
      '%op' => $msg,
      '%pointsvalue' => abs($params['points']),
      '%total' => userpoints_get_current_points($params['uid'], $params['tid']),
    )));
  }

  //if $params['status']
  if ($mesg && (!empty($params['display']) || empty($params['display']) && 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);
  return array(
    'status' => TRUE,
  );
}