function userpoints_userpointsapi in User Points 7

Same name and namespace in other branches

5.3 userpoints.module \userpoints_userpointsapi()
5 userpoints.module \userpoints_userpointsapi()
5.2 userpoints.module \userpoints_userpointsapi()
6 userpoints.module \userpoints_userpointsapi()

Save userpoints changes and call hooks.

Parameters

$params: 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 assignment 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

11 calls to userpoints_userpointsapi()

MigrateDestinationUserpoints::import in ./userpoints.migrate.inc: Import a single userpoints transaction.
UserpointsAPITestCase::testBasicCall in tests/userpoints_api.test: Call userpoints_userpointsapi() with just points.
UserpointsAPITestCase::testEditingTransactions in tests/userpoints_api.test: Test that editing points correctly updates the current and max points.
UserpointsAPITestCase::testExpiration in tests/userpoints_api.test
UserpointsAPITestCase::testModeration in tests/userpoints_api.test

... See full list

File

./userpoints.module, line 813

Code

function userpoints_userpointsapi($params) {
  global $user;

  // 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_int($params)) {
      $params = array(
        'points' => $params,
      );
    }
    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'])) {
      $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'] = userpoints_get_default_tid();
    }

    // Anonymous users do not get points, and there have to be points to process.
    if (empty($params['uid']) || empty($params['points'])) {
      return array(
        'status' => FALSE,
        'reason' => 'uid or points not given. 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_query('SELECT uid from {userpoints_txn} WHERE txn_id = :txn_id', array(
      ':txn_id' => $params['txn_id'],
    ))
      ->fetchField();
  }

  // If txn_id.
  // Load the user object that will be awarded the points.
  $account = user_load($params['uid']);
  if (!$account) {
    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 = userpoints_invoke_all('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,
        )),
      );
    }
  }
  $ret = _userpoints_transaction($params);

  // Reset the static cache of userpoints.
  drupal_static_reset('userpoints_get_current_points');
  if ($ret == FALSE) {
    return array(
      'status' => FALSE,
      'reason' => 'transaction failed in _userpoints_transaction, this is an internal module error',
    );
  }

  // Allow modules to define custom messages.
  if (!empty($params['message'])) {
    $message = $params['message'];
  }
  elseif (!empty($params['display']) || !isset($params['display']) && variable_get(USERPOINTS_DISPLAY_MESSAGE, 1)) {

    // Prepare arguments. They are the same for all string combinations.
    $categories = userpoints_get_categories();
    $arguments = array_merge(userpoints_translation(), array(
      '!username' => theme('username', array(
        'account' => $account,
      )),
      '%total' => userpoints_get_current_points($params['uid'], $params['tid']),
      '%category' => isset($categories[$params['tid']]) ? $categories[$params['tid']] : $categories[0],
    ));
    $view_own_points = user_access('view own userpoints') || user_access('view userpoints') || user_access('administer userpoints');
    $view_all_points = user_access('view userpoints') || user_access('administer userpoints');
    if ($params['status'] == USERPOINTS_TXN_STATUS_DECLINED) {

      // Points have been declined.
      if ($account->uid == $user->uid && $view_own_points) {
        $message = format_plural($params['points'], 'You did not receive approval for @count !point in the %category category.', 'You did not receive approval for @count !points in the %category category.', $arguments);
      }
      elseif ($view_all_points) {
        $message = format_plural($params['points'], '!username did not receive approval for @count !point in the %category category.', '!username did not receive approval for @count !points in the %category category.', $arguments);
      }
    }
    elseif (isset($params['points']) && $params['points'] < 0) {
      if ($params['status'] == USERPOINTS_TXN_STATUS_PENDING) {
        if ($account->uid == $user->uid && $view_own_points) {

          // Directly address the user if he is loosing points.
          $message = format_plural(abs($params['points']), 'You just had a !point deducted, pending administrator approval.', 'You just had @count !points deducted, pending administrator approval.', $arguments);
        }
        elseif ($view_all_points) {

          // Only display message about other users if user has permission to view userpoints.
          $message = format_plural(abs($params['points']), '!username just had a !point deducted, pending administrator approval.', '!username just had @count !points deducted, pending administrator approval.', $arguments);
        }
      }
      else {
        if ($account->uid == $user->uid && $view_own_points) {
          $message = format_plural(abs($params['points']), 'You just had a !point deducted and now have %total !points in the %category category.', 'You just had @count !points deducted and now have %total !points in the %category category.', $arguments);
        }
        elseif ($view_all_points) {
          $message = format_plural(abs($params['points']), '!username just had a !point deducted and now has %total !points in the %category category.', '!username just had @count !points deducted and now has %total !points in the %category category.', $arguments);
        }
      }
    }
    elseif (!empty($params['points'])) {
      if ($params['status'] == USERPOINTS_TXN_STATUS_PENDING) {
        if ($account->uid == $user->uid && $view_own_points) {

          // Directly address the user if he is loosing points.
          $message = format_plural(abs($params['points']), 'You just earned a !point, pending administrator approval.', 'You just earned @count !points, pending administrator approval.', $arguments);
        }
        elseif ($view_all_points) {

          // Only display message about other users if user has permission to view userpoints.
          $message = format_plural(abs($params['points']), '!username just earned a !point, pending administrator approval.', '!username just earned @count !points, pending administrator approval.', $arguments);
        }
      }
      else {
        if ($account->uid == $user->uid && $view_own_points) {
          $message = format_plural(abs($params['points']), 'You just earned a !point and now have %total !points in the %category category.', 'You just earned @count !points and now have %total !points in the %category category.', $arguments);
        }
        elseif ($view_all_points) {
          $message = format_plural(abs($params['points']), '!username just earned a !point and now has %total !points in the %category category.', '!username just earned @count !points and now has %total !points in the %category category.', $arguments);
        }
      }
    }
    if (isset($message)) {
      drupal_set_message($message);
    }
  }

  // Call the _userpoints hook to allow modules to act after points are awarded.
  userpoints_invoke_all('points after', $params);
  return array(
    'status' => TRUE,
    'transaction' => $params,
  );
}

You are here

function userpoints_userpointsapi in User Points 7

Parameters

Return value

File

Code

API Navigation