The points for each user are stored in two places: in the user meta table, and in the points logs.
The points stored in the user meta table is the actual number of points that each user has for each points type. (Note that it is possible that this will be stored in its own table in the future.)
WordPoints does not calculate the number of points that a user has based on the points logs. That would make the plugin do a lot of work each time it wanted to know how many points a user has. It would make it very difficult to show a list of the users with the most points, for example. That is why the plugin keeps track of the number of points of each points type for each user. We will refer to this value as the total.
The total is the value that WordPoints uses. The number of points is never calculated from the logs. In fact, it is possible that total would be a different amount from what you could calculate from the logs. That is because it is possible to modify a user’s points without logging the transaction, or delete a log without modifying the points. The plugin does not do either of these things, but they are possible.
So, there is a difference between the total and what you would calculate from the logs. Usually they will be same, but it is possible that sometimes they could be different.
This is important to remember whenever you are planning to do something with the amount of points in the points logs.
You should also be very careful about modifying either the logs or the totals. You should always use the functions provided by WordPoints to modify these values, instead of performing direct queries.
There should almost never be a reason that you would modify the total points of a user without logging the transaction, or vice versa. However, if you do need to do this, please keep these things in mind:
- You will be desynchronizing the two values (this should be obvious).
- This could have unintended side effects for other code that compares the two values in some way.
- It’s not possible to know what issues this might cause, so think very carefully before doing this!
In most cases, it would probably be better to log a transaction, but hide it from users if needed.
If you are planning to use a points value calculated from the logs, you should keep this in mind:
- It is possible that the value calculated from the logs won’t exactly match the user totals.
- However, it is safe for you to assume that in most cases the two values will match.
- But your code should not break if there is a discrepancy between the numbers.
- When there is a discrepancy, your code should just assume that a transaction has purposely not been logged.