function userpoints_userpointsapi in User Points 5

Same name and namespace in other branches

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

Parameters

op: operation to be performed.: 'points' modules should use this to award points 'points before' hook that fires before points are added 'points after' hook that fires after points have been added

points: number of points to add (if positive) or subtract (if negative):

uid: user id of the user to get or lose the points:

event: optional event ID:

description: optional description :

reference: optional reference information, indexed:

Return value

FALSE when no action is take, TRUE when points are credited or debited

4 calls to userpoints_userpointsapi()

userpoints_admin_approve in ./userpoints.module

userpoints_admin_txn_submit in ./userpoints.module

userpoints_comment in ./userpoints_basic.module

userpoints_nodeapi in ./userpoints_basic.module

File

./userpoints.module, line 229

Code

function userpoints_userpointsapi($op, $points = 0, $uid = 0, $event = NULL, $description = NULL, $reference = NULL) {

  // anonymous users do not get points, and there have to be points to process
  if ($uid == 0 || $points == 0) {
    return FALSE;
  }

  // When called explicitly, we handle only three cases. The rest are hooks
  // that should be defined in other modules.
  if ($op != 'points' && $op != 'txn approve' && $op != 'points approved') {
    return FALSE;
  }

  // Load the user
  $user = user_load(array(
    'uid' => $uid,
  ));

  // Call the _userpoints hook, and stop if one of them returns FALSE
  // This will be handy later
  $rc = module_invoke_all('userpoints', 'points before', $points, $uid, $event);
  foreach ($rc as $key => $value) {
    if ($value == FALSE) {

      // Do not process the points
      return FALSE;
    }
  }
  if ($points < 0) {
    $msg = t('lost');
  }
  else {
    $msg = t('earned');
  }

  // If $op is 'points', then the points MAY or MAYBE NOT subject to
  // approval, depending on user settings. If they are, then
  // write the transaction (with the noderation flag on) and return - which
  // will provent the rest of the function from actually assigning the
  // points
  if ($op == 'points') {
    $moderation = variable_get(USERPOINTS_POINTS_MODERATION, FALSE);
    userpoints_transaction($moderation, $points, $uid, $event, $description, $reference);

    // If points are being moderated, then write a message to the user and
    // that's it!
    if ($moderation) {

      // Points are moderated, so we do nothing for now.
      drupal_set_message(t('User %uname %op %pointsvalue !points, pending administrator approval.', array_merge(userpoints_translation(), array(
        '%uname' => $user->name,
        '%op' => $msg,
        '%pointsvalue' => abs($points),
        '%total' => $current_points,
      ))));
      return TRUE;
    }
  }

  // If the points are pre-approved, then just write the trail
  if ($op == 'points approved') {
    userpoints_transaction(FALSE, $points, $uid, $event, $description, $reference);
  }

  // ***********************
  // At this point, regardless of what $op is, the module needs to
  // actually award the points. (Keep in mind that if $op was 'point' and
  // moderation was on, then it won't get to this part).
  // ***********************
  // Calculate the current point
  $current_points = (int) $points + userpoints_get_current_points($uid);

  // Check if user has earned points
  if ($points > 0) {

    // Set the max_points to be the current max points, plus whatever earned in this transaction
    $max_points = db_result(db_query('SELECT max_points FROM {userpoints} WHERE uid = %d', $uid));
    $max_points = $current_points + (int) $max_points;
  }
  drupal_set_message(t('User %uname %op %pointsvalue !points! Total now is %total points.', array_merge(userpoints_translation(), array(
    '%uname' => $user->name,
    '%op' => $msg,
    '%pointsvalue' => abs($points),
    '%total' => $current_points,
  ))));
  if (_userpoints_user_exists($uid)) {
    db_query("UPDATE {userpoints}\n      SET points = %d, max_points = %d, last_update = %d WHERE uid = %d", $current_points, $max_points, time(), $uid);
  }
  else {
    $result = db_query("INSERT INTO {userpoints}\n      VALUES (%d, %d, %d, %d)", $uid, $current_points, $max_points, time());
  }
  module_invoke_all('userpoints', 'points after', $points, $uid, $event);
  return TRUE;
}