myCRED_Query_Log
Description
This class allows you to search the myCRED Log for entries based on a large variety of options. Similar to the WP_Query class, you can use this class to query and then loop through the results in order to show the results in any way you like. Currently the class also has a large set of functions to help you render a table where these results are presented. This feature is currently used by the Log module in your admin area and by the mycred_history shortcode / widget.
In version 1.8, this class will be split up and focus on running queries in the database while a separate class will be made available that will render the table to show the results.
This documentation is for version 1.7 or later which was introduced in myCRED 1.7.5.
Interacting with the Class
While the class offers a large number of functions for you to use, your most common interaction will be with constructing and providing arguments for your search.
// Example 1: Show the last 10 entries $args = array( 'number' => 10 ); // The Query $log = new myCRED_Query_Log( $args ); // The Loop if ( $log->have_entries() ) { // Display using the built-in table $log->display(); }
// Example 2: Get log entries for user 1 $args = array( 'user_id' => 1 ); // The Query $log = new myCRED_Query_Log( $args ); // The Loop if ( $log->have_entries() ) { // Build your custom loop foreach ( $log->results as $entry ) { // Present the results anyway you like } }
Class Properties
Property | Declared | Type | Description |
---|---|---|---|
$now |
Public | int | The current unix timestamp. Used for date / time rendering and parsing. |
$render_mode |
Public | bool | Indicates if the class allows results to be rendered using the built-in methods or if only queries can be made. Added in 1.7.5 |
$args |
Public | array | Holds the arguments that the class was constructed around. |
$request |
Public | string | The SQL query that was run to get the results you are seeing. |
$num_rows |
Public | int | The number of rows the query returned. |
$max_num_pages |
Public | string | The maximum number of pages the results span over. Defaults to 1. |
$total_rows |
Public | int | The total number of rows in the database. |
$results |
Public | array | The results of your query. |
$headers |
Public | array | Holds an associative array of headers that the table will render. |
$hidden_headers |
Public | array | Holds an array of header ids that you have selected to hide. |
$core |
Public | object | The myCRED_Settings class object. |
$is_admin |
Public | bool | Indicates if the class is used in the front end or in the wp-admin area. |
$references |
Public | array | An array of reference IDs and their labels. This is used to translate each log entries reference when displayed in the table. |
$refs |
Public | array | An array containing all references that exists in the database, based on the current query. Added in 1.7.5 |
$types |
Public | array | Populated with the myCRED_Settings object for each point type we are searching for. This is used when you are rendering a table for the query results with multiple point types. Added in 1.7.5 |
Class Parameters
Parameter | Type | Required | Description |
---|---|---|---|
$args |
array | Yes | The query arguments to return results for. |
$array |
bool | No | Option to return entries in an array format instead of object format. Can not be used when the fields argument is set to return a specific column. |
Query Arguments
Arguments can be passed in string or array format. When using a string format, you separate each argument with an & character. String format is well suited in simple straightforward queries, however for more advanced queries, an array format is required.
Entry IDs
Argument | Type | Description |
---|---|---|
entry_id |
array or int | Retrieve log entries based on their unique ids. Supports queries of a single id or multiple ids. Supports = , != , IN and NOT IN comparisons. |
Example 1: Get a single entry that has the id 1
$log = new myCRED_Query_Log( 'entry_id=1' );
Example 2: Get multiple entries
$log = new myCRED_Query_Log( array( 'entry_id' => array( 1, 2, 3 ) );
Example 3: Get entries that does not have the ids 1 or 2
$args = array( 'entry_id' => array( 'ids' => array( 1, 2 ), 'compare' => 'NOT IN' ) ); $log = new myCRED_Query_Log( $args );
Example 4: Get entries that does not have the id 5
$args = array( 'entry_id' => array( 'ids' => 5, 'compare' => '!=' ) ); $log = new myCRED_Query_Log( $args );
Point Types
Argument | Type | Description |
---|---|---|
ctype |
array or string | Retrieve log entries of a particular point type or multiple types based on the point type key. Supports = , != , IN and NOT IN comparisons. |
If this argument is not set, the class will set it to show entries of the main point type. To show entries no matter which point type they belong to, make sure you set this attribute to an empty string.
Example 1: Get entries of the default point type
$log = new myCRED_Query_Log( 'ctype=mycred_default' );
Example 2: Get entries of a custom point type
$log = new myCRED_Query_Log( array( 'ctype' => 'mycustom_type' ) );
Example 3: Get entries that are not of a custom point type
$args = array( 'ctype' => array( 'ids' => array( 'mycustom_type', 'anothertype' ), 'compare' => 'NOT IN' ) ); $log = new myCRED_Query_Log( $args );
Example 4: Get entries of all point types
$log = new myCRED_Query_Log( array( 'ctype' => '' ) );
User IDs
Argument | Type | Description |
---|---|---|
user_id |
array or int | Retrieve log entries one or multiple users based on their numeric IDs. Supports = , != , IN and NOT IN comparisons. |
user_id
ARRAY or STRING
Retrieve log entries one or multiple users based on their numeric IDs. Supports =
, !=
, IN
and NOT IN
comparisons.
If you do not know the users numeric ID, you can always use the mycred_get_user_id function which supports converting usernames, email addresses or slugs into numeric IDs (assuming a user is found to match)
Example 1: Get entries for the user with the ID 1
$log = new myCRED_Query_Log( 'user_id=1' );
Example 2: Get entries for a set of users
$log = new myCRED_Query_Log( array( 'user_id' => array( 1, 2, 4 ) ) );
Example 3: Get entries that do not belong to users 1, 2 and 6
$args = array( 'user_id' => array( 'ids' => array( 1, 2, 6 ), 'compare' => 'NOT IN' ) ); $log = new myCRED_Query_Log( $args );
References
Argument | Type | Description |
---|---|---|
ref |
array or string | Retrieve log entries based on one or multiple references. Supports = , != , IN and NOT IN comparisons. |
Example 1: Get all manual entries
$log = new myCRED_Query_Log( 'ref=manual' );
Example 2: Get entries for approved comments and published content
$log = new myCRED_Query_Log( array( 'ref' => array( 'approved_comment', 'published_content' ) ) );
Example 3: Get all entries that are not manual
$args = array( 'ref' => array( 'ids' => 'manual', 'compare' => '!=' ) ); $log = new myCRED_Query_Log( $args );
Example 4: Get all entries of a custom reference
$args = array( 'ref' => array( 'ids' => 'mycustomreference', 'compare' => '=' ) ); $log = new myCRED_Query_Log( $args );
Reference IDs
Argument | Type | Description |
---|---|---|
ref_id |
array or int | Retrieve log entries based on one or multiple reference IDs. Supports = , != , < , <= , >= , IN and NOT IN comparisons. |
Example 1: Get all entries with the reference id 1
$log = new myCRED_Query_Log( 'ref_id=1' );
Example 2: Get entries with a reference id of 1, 2 or 3
$log = new myCRED_Query_Log( array( 'ref_id' => array( 1, 2, 3 ) ) );
Example 3: Get all entries with a reference id lower than 100
$args = array( 'ref_id' => array( 'ids' => 100, 'compare' => '<' ) ); $log = new myCRED_Query_Log( $args );
Example 4: Get all entries that have a reference id higher or equal to 10, no matter which point type the entry belongs to
$args = array( 'ref_id' => array( 'ids' => 10, 'compare' => '>=' ), 'ctype' => '' ); $log = new myCRED_Query_Log( $args );
Point Amounts
Argument | Type | Description |
---|---|---|
amount |
array or int or float | Retrieve log entries based on one or multiple amounts. Supports = , != , < , <= , >= , BETWEEN , NOT BETWEEN , IN and NOT IN comparisons. |
Example 1: Get all entries were users gained 1000 points
$log = new myCRED_Query_Log( 'amount=1000' );
Example 2: Get entries where a user gained 10, 20 or 50 points
$log = new myCRED_Query_Log( array( 'amount' => array( 10, 20, 50 ) ) );
Example 3: Get all entries where a user has gained between 0 and 100 points
$args = array( 'amount' => array( 'num' => array( 0, 100 ), 'compare' => 'BETWEEN' ) ); $log = new myCRED_Query_Log( $args );
Example 4: Get all entries where a user lost points, no matter which point type
$args = array( 'amount' => array( 'num' => 0, 'compare' => '<' ), 'ctype' => '' ); $log = new myCRED_Query_Log( $args );
Time
Argument | Type | Description |
---|---|---|
time |
array or int or string | Retrieve log entries for a given time period or date/time. You can supply a well formatted date/time string, a unix timestamp or a keyword. Supported keywords: today , yesterday , thisweek and thismonth . Supports = , != , < , <= , >= , BETWEEN , NOT BETWEEN , IN and NOT IN comparisons. |
myCRED stores dates in unix timestamp format. If you do not provide a unix timestamp, the class will use strtotime to convert your given date/time into a unix timestamp. This allows you to to use keywords that strtotime accepts along with dates/times.
If you provide a date but not a time, the class will query entries up until the end of the day and not the beginning of the day! If this is not desired, make sure you also include a time with your date.
Example 1: Get todays entries
$log = new myCRED_Query_Log( 'time=today' );
Example 2: Get all entries for a specific date
$log = new myCRED_Query_Log( array( 'time' => '2016-10-01' ) );
Example 3: Get all entries between two dates
$args = array( 'time' => array( 'dates' => array( '2016-01-01 00:00:01', '2016-12-31 23:59:59' ), 'compare' => 'BETWEEN' ) ); $log = new myCRED_Query_Log( $args );
Example 4: Get all entries before the start of today
$args = array( 'time' => array( 'dates' => 'today midnight', 'compare' => '<' ) ); $log = new myCRED_Query_Log( $args );
Searching
Argument | Type | Description |
---|---|---|
s |
int or string | Search the "entry" columns and retrieve entries that match. You can use wildcards % for LIKE comparisons. |
data |
int or string | Search the "data" columns and retrieve entries that match. You can use wildcards % for LIKE comparisons. |
As of version 1.7.5, no wildcards are added to the search string automatically. Instead you are required to add them in. If no wildcards are used, the class will search the value exactly.
Example 1: Get entries that has the string “boo“ in their description
$log = new myCRED_Query_Log( 's=boo' );
Example 2: Get entries where the “entry“ columns content starts with “Tokens“
$log = new myCRED_Query_Log( array( 's' => 'Tokens%' ) );
Example 3: Get entries that has the string “boo“ in their data column
$log = new myCRED_Query_Log( 'data=boo' );
Example 4: Get entries where the “data“ columns content a serialized array
$log = new myCRED_Query_Log( array( 'data' => 'a:1:{s:8:"ref_type";s:4:"user";}' ) );
Sorting of Results
Argument | Type | Description |
---|---|---|
orderby |
array or string | Sort the retrieved log entries. As of version 1.7.5 you can sort by multiple columns by providing an array of columns and their order. |
order |
string | Either ASC for ascending or DESC for descending. Ignored if orderby is an array. |
Example 1: Get entries for the user 1 ordered by time in an ascending order (latest entry is shown last)
$args = array( 'user_id' => 1, 'orderby' => 'time', 'order' => 'ASC' ); $log = new myCRED_Query_Log( $args );
Example 2: Get “Manual“ entries sorted by the point amount (largest first), then by time
$args = array( 'ref' => 'manual', 'orderby' => array( 'creds' => 'DESC', 'time' => 'DESC' ) ); $log = new myCRED_Query_Log( $args );
Return Fields
Argument | Type | Description |
---|---|---|
fields |
array or string | Either the name of a particular column or an array of column names you want returned in your results. See the log structure documentation for accepted values. |
ids |
bool | Option to only return the log entries unique ID. Depreciated since 1.7.5 and will be removed in future versions in favour for fields . |
The fields argument was introduced in version 1.7.5 and is not available on older versions! If you use this argument, you will not have access to the table rendering methods in this class as these methods were built to show results from all columns and not just some / one. If used, the $render_mode
Parameter will switch to FALSE
.
Example 1: Get the log entry ids only for a specific user
$args = array( 'user_id' => 1, 'fields' => 'id' ); $log = new myCRED_Query_Log( $args );
Example 2: Get the log entry ids and the point amounts only for a specific user
$args = array( 'user_id' => 5, 'fields' => array( 'id', 'creds' ) ); $log = new myCRED_Query_Log( $args );
Pagination
Argument | Type | Description |
---|---|---|
number |
int | The number of entries to return. By default this is 25. Use -1 to return all entries. If you are rendering the results in the class table, this will be the number of entries shown per page. |
paged |
int | The page number. Retrieve entries that would show on page x when using the navigation. Defaults to 1 as in the first page. |
offset |
int | Number of entries to displace or pass over. Should be used in combination with number . Defaults to zero. |
It is not recommended to show all log entries when you intend to render then in the class table! If you do, the page will load slower and slower as the number of entries increase!
Example 1: Show 15 entries per page
$args = array( 'user_id' => 1, 'number' => 15 ); $log = new myCRED_Query_Log( $args );
Example 2: Get all manual log entries
$args = array( 'ref' => 'manual', 'number' => -1 ); $log = new myCRED_Query_Log( $args );
Query Filters
Your query will trigger the following filters whenever the class is constructed:
Filter | Description |
---|---|
mycred_query_log_args | Allows you to manipulate the query arguments before it is processed by the class. |
mycred_allowed_sortby | Controls what values the query can be sorted by. By default this is the log column headers. |