Userpoints 3.x API changes

I was reading http://drupal.org/node/142956 and the following caught my eye.
$op can be
'points' - Points are awarded instantly and adhere to the sites moderation rules
'txn approve' - Points are approved, and the trail is ignored.
'points approved' - Points are awarded instantly and moderation is ignored

In the new API change what would $op be? Because there seems to be unanimous agreement that ALL transactions should be stored. Would it be better to drop $op and instead have a boolean $moderate flag?

Examples:
Current consideration:

$arg = array(
'op' => 'points',
'points' = $points,
);
userpoints_userpointsapi($arg);

The change

$arg = array(
'moderate' => FALSE, 
'points' = $points,
);
userpoints_userpointsapi($arg);

if $arg['moderate'] is NULL then the site's moderation rules apply.
if TRUE then points are moderated regardless of the moderation settings (would that even make sense?)

I only say $opt as being 'points', 'txn approve' or 'points unmoderate'. Since 'txn approve' skips past the txn table (no audit trail) and everyone agree that is bad.. should be drop it completely?

Is there a module/case that would really like to keep txn_approve (skip the txn table)? (super high traffic sites/modules.. possibly?)

Also another comment, shouldn't the minimum call include $uid or if its not pass in would the code take $user->uid?
example

$arg = array(
'op' => 'points',
'points' => $points,
'uid' => $user->uid
);
userpoints_userpointsapi($arg);

OK :: $uid. agreed not needed we'll default to $user->uid (as we currently do). I like the minimal call
$op :: if we kept it we don't need $moderated since we can simply have multiple ops
'points' = Add points and adhere to module defaults
'points approve' = Add points and skip moderation (override module defaults)
'txn approve' = Add points, no moderation, no trail

In regards to txn approve, I see the merit in it for performance reasons. If you're on a website granting a single point for every comment, node, revision, etc. and you're getting thousands/tens-of-thousands of comments/node/revisions a day the userpoints_txn table is going to fill up fast. After a few months it could potentially be filled with 100s of thousands of entries or millions.

Which could affect performance. <-- feedback requested, please

If so should we allow an option to ignore the trail? (which destroys auditing.. but if that's what the users want.. whatever..right?)

Also while we're at it.. should we change the naming convention to something like
'points'
'points approve'
'points notxn'

Just so its a little more intuitive. Because honestly 'txn approve' to me says "Transaction approve' or that a transaction log will be created vs. simply points.

Thoughts?

I recently committed the v3 API changes to the BRANCH DRUPAL-5--3. userpoints_api now accepts an array of parameters instead

ex. userpoints_userpointsapi($params = array())

$params requires at a minimum
'op' => 'points' OR 'points approved' (points approved skips moderation)
'points' => (int)

$params can currently contain
$uid (default = $user->uid)
$event (string)
$expirydate = (timestamp when point should expire)
$description = (string)
$reference = indexed, searchable for module use

expirydate is a NEW feature that I added that expires points on a certain date (via cron) by posting an opposite transaction (5 points is expired by adding a -5 points). A trail is always logged.

userpoints_transaction was also modified to accept an array (same as userpointsapi)

example of how to use the new API call
$params = array(
'op' => 'points',
'points' => 10,
'uid' => $user->uid,
'event' => 'admin',
'description' => "Adding a node",
);
userpoints_userpointsapi($params);

due to the changes in the API $op only operates on 'points' and 'points approve'. We could simply the api call and the and api function by reducing to a simple $moderate that would default to the site's setting. Thus the api call could be as simple as

userpointsapi(array('points' => 5))

which we could then reduce even more by testing if $param is_numeric or an array and if numeric assume that its a point. Similar to node_load.

ex. userpointsapi(5);

Those points would then be assigned to the current logged in user and adhere to the site's default settings for moderation, expiration, etc.

Thus the remaining question is :: Can we drop $op and move to $moderated = TRUE/FALSE?

1. Would that be a mechanism where a module can bypass the site setting re: moderation (e.g. site says moderate them, but module X says grant them immediately)?

Yes effectively. $moderate would have the following states
moderate = TRUE (moderate regardless of site settings)
moderate = FALSE (bypass moderation regardless of site settings)
moderate = NULL or not set (adhere to site settings)

It seemed as though some modules wanted to explicitly bypass the moderation status (ex. $op = "txn approve" bypassed moderation)

2. Are you sure we won't need $op for any other cases (e.g. txn approve, ...etc.)?

I don't know the answer to this. Currently "Points before" and "points after" are available for all modules to act on but $op isn't sent onto other modules (thus by dropping this we wouldn't affect them). Within the module itself $op was only being tested for two settings; "points" and "points approve". The only difference was that "points approve" bypassed moderation "txn approve" was being used for points given by an administrator but switching this to moderate = FALSE would solve that issue (and $op isn't being stored anywhere). There is still $event in the DB (and passed via the API call) which (a) is stored in the DB and (b) we could send onto to other module for them to act on.

I have only been using this module for the past several months but I haven't seen any reason for keeping $op going forward. If someone with a longer history of this module could comment it would be greatly appreciated.

Revision 1.44.2.14.2.9 in the DRUPAL-5--3 branch implements the API change including the change to $moderation instead of $op.

Version 3 is NOT ready for release as the contributed modules haven't been updated yet.

Hi,

For what it's worth, please accept my apologies for missing this thread. I was travelling... I've only just managed to come back to my normal working life :-(

Hey merc! Welcome back. No problem about missing the thread but when you get some time could you grab the dev version of 3 and put it threw the ringer. All comments are fully appreciated.

Thank you for your understanding :-D
OK, I will go through the thread and will have a look!

simple_karma will need to talk to userpoints. So, I will definitely test this a lot...

Bye,

Merc.