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

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.

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.