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.
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 } }
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 |
The class has only two parameters that you can use.
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. |
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. |
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. |
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. |
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. |
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 . |
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. |
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 );
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. |