myCRED_Query_Log - myCRED Codex

myCRED_Query_Log

Codex / mycred/log / Classes / 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.

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.