wordpoints / top-users-in-period

Display the top points earners within a given period of time

WordPoints

This is where development of the WordPoints WordPress plugin takes place. To download the latest stable release, seek support, or for more information about the plugin, see its home on WordPress.org. You may also want to visit the plugin's website, where you'll find user and developer documentation.

Reporting a bug

If you find a bug in the plugin, please report it here. Before opening a new issue, always be sure that you have searched the existing issues to make sure your bug is new. In your report be as detailed as possible, and be sure to include a list of steps to reproduce the bug. Please also give as much information as you can about your WordPress install and its envireonment: WordPress and PHP versions, active plugins, etc.

Whatever you do: never, ever report a bug for an old version of WordPoints. Make sure that you have the latest version installed before filing an issue. If possible, test that the bug exists in the development trunk as well.

If you aren't sure what all that means (or sometimes maybe even if you are) you should probably seek help in the support forums instead.

Security

See SECURITY.md.

Contributing

See CONTRIBUTING.md.

top-users-in-period's Issues

Only load module code when points component is active

It relies on the points component, so if it happens to be inactive for some reason, it can break the site.

Flush cache based on new log points values

As a follow-up to #7, at some point in the future we could be even smarter about invalidating the caches, as it relates the points column.

And in addition to just handling the points query args, we could also detect when a transaction could affect who was in the top users. Not all transactions can. For example, when a user who is not among the top users has points removed, they can't possibly be moved into the top users based on that (except perhaps for certain special query arg combinations?).

Don't publish blocks if filling them fails

A user has had issues where some of the blocks were published but not filled in at all. We haven't yet gotten to the root cause of the issue, but I think a little sanity check here is needed.

Clean block logs on points type delete

Similar to #12.

However, in this case it is slightly more complex, because points type query args are incorporated into the block signatures. So this isn't just about trimming the block logs, this is actually about cleaning out whole blocks. And we really can't do that without knowing what args are behind their signatures. Since the signatures are hashes, we don't know which blocks belong to which points types.

Database error when counting block logs

The block logs query does not override the count() method to give any kind of warning like the main query does, so it would seem that the count() method is intended to be usable. However, attempting to use it will produce a database error:

WordPress Database Error: Unknown column 'total' in 'order clause' [SELECT COUNT(*)
FROM `wptests_wordpoints_top_users_in_period_block_logs`
WHERE `user_id` = 5
GROUP BY `user_id`

ORDER BY `total` DESC
]

We need to prevent this by either giving a higher-level error and essentially disabling the method, or making the method work.

The issue is the ORDER BY clause, which references the total column. It isn't a column at all, but the sum of the points column, which we aren't calculating when we are just counting.

Probably the order clause can be omitted here, since it seems irrelevant to counting. Perhaps that should even be pulled upstream so that the order clause is always omitted from count queries. But regardless we'll need to fix this here in some way.

Pagination

Mainly just needed on the admin screen right now (#3), though it may also be needed by the shortcode (#2).

Widget to display top users for period

Optimization for queries that have no end date

We introduced a basic caching API in #6, and it works fine for queries that extend over a fixed period, from date one to date two. However, the more common use-case will generally be open-ended queries, that extend from some past point to the present.

While working on the widgets (#1), we have optimized the queries that it uses so that for queries measured in anything longer than seconds, there will be a particular start date that is reused over a period of time. That is, there will still be a fixed start date for the query, that will remain the same for several minutes, hours, days, weeks, or months, depending on how long of a period of time the query is for.

So we have queries that are anchored at the start end, meaning that only the end date is dynamic. The end date is basically rolling, remaining always at the current second, while the start date will jump in discrete steps, points that we can anchor a cache to.

The problem is that our caching currently always takes into account both the start and end dates for the query. It doesn't treat queries which have no specified end date as special (in fact, the present date is just filled in). On the positive side, this means that the cache does not need to ever be invalidated, because the queries are always anchored on both ends, and the log history is unlikely to change (and we couldn't really detect if it did anyway). On the other hand, it also means that after the query is cached it is unlikely to be reused, because even if the start date is the same, the end date will have moved on, even if only by a few seconds.

So what we need to do to optimize for this is to provide a way for open-ended, to-the-present, queries, to be cached only based on their start date.

Caching

While working on #4, I've build the query so that a caching class will be separate, so that the caching method can be changed, even on a per-query basis.

By default, I was thinking of using WordPress's caching API, but I always figured we'd probably need to do something special for sites that aren't using any form of persistent caching. We could use the transients API, but the drawback there is that we have to truncate the query signatures. We only have 40 characters, because we have to use the site transients.

Clean block logs on user delete

Actually, we would need to clear the cache too, I guess.

How to handle users who have earned no points within a period

Something that we'll have to decide is how to handle users who have not earned any points in a given period.

In the wordpoints_points_get_top_users() function in core, we query the users table with a LEFT JOIN on the usermeta table. Essentially, we include the users with no points in the list of top users. This is partly because of complaints about the table being empty, or not showing some users. Or really, I guess it was about the table showing less than the number of requested users. But the reason for that was because the site did not have very many users with points yet.

Showing the non-earners in the table makes the query more expensive, and it really has little value, as far as I can tell, so I'm leaning against it. Instead, I'd suggest that we add a row that contains a message that there were no more points earners within the period, or something to that effect.

Clean empty in/not in conditions from query args

These don't affect the query, so they shouldn't be made part of the query signature. It just wastes space in the database by duplicating the results between queries with the empty condition and those without it.

Add query class

This is different than the top users query in core's wordpoints_points_get_top_users() function. That function is just about the current top users, so it performs a user query with usermeta. However, in this case we are summing over a period of time, so we are actually performing a query on the points logs.

Of course, core includes the WordPoints_Points_Logs_Query class. The problem is that to use it we would have to pull out all of the values for a given period and then perform the calculation of the sum of points for each user in PHP.

That might be the best way to go at times, but I think that we should give ourselves the option to actually do the sum in the query itself as well. So of course the code for querying for the top users in a period should be abstracted into a single location, and probably a class is the best solution, since things might get fairly complex.

Remove Channel header in favor of Server

We would wait until WordPoints 2.4.0 is released, but it is failing our builds due to the deprecated error in the uninstall tests. So I see no reason to wait.

Query: secondarily order by user ID

We now do this for the top users in core. See WordPoints/wordpoints#673.

Admin screen to view the most active users

This was specifically requested. In theory the same thing could be achieved via shortcode on the front end, the admin can view it just like everybody else. However, that could potentially be more of a performance hit. And maybe the admin doesn't want to have to expose all of that to everyone.

Shortcode to display top users for period

Cached query shown when to date is in the future

A shortcode like this will show the same results after the first time the query is executed, even if the end date is in the future, and so points affecting the period are still being awarded.

[wordpoints_top_users_in_fixed_period from=2017-05-01 to=2017-05-31]