Rating query object

To search and filter rating items, GD Rating System includes easy to use object, that will construct and run the rating query. This object allows you to set various query arguments to fine tune the results.

Object name is ‘gdrts_core_query’. To get the initialized object, you can use the function gdrts_query() that will return already prepared object, but you can make your own instance too. This object has an own main method that will prepare and run the query, and return results.

Basic usage:

$args = array(); // list of arguments
$ratings = new gdrts_core_query();
$results = $ratings->run($args);

Variable $args needs to be an array that includes a list of arguments you want to use to filter and order list or results.

Supported arguments

Here are the supported arguments:

• method – the name of the rating method to use, default is ‘stars-rating’.
• series – the name of the rating series for emote-this rating method.
• entity – the name of the rating type entity.
• name – the name of the rating type.
• id__in – a list of rating item ID’s to limit the results.
• id__not_in – a list of rating item ID’s to exclude.
• orderby – the column to use for sorting: item, id, latest, up, down, votes, percentage, sum, rating. The default is ‘rating’.
• order – a sorting order: DESC or ASC, default is DESC.
• offset – the number of results to skip, default is 0.
• limit – the number of results to return, default is 5.
• return – what format of data to return: objects, ids and quick. Default is ‘objects’.
• rating_min – a minimum rating to consider for filtering. The default is 0.
• votes_min – a minimum number of votes to consider for filtering. The default is 1.
• object – additional data for filtering the rating items.

Some values for orderby are for the Thumbs Rating method only: up and down.

Object argument

The last argument called ‘object’ is an array for specifying additional filters specific to the rating items original data (posts, terms…).

This argument is available in Pro version of the plugin only!

Object array supports these elements, and each one can be an array with values:

• status: publish status for posts, by default ‘publish’, ‘inherit’ and ‘closed’.
• post_type: post type name, used for comments.
• date: publication dates or date range, for posts.
• author: a list of IDs of the authors for posts or comments.
• meta: a simple associative array of meta key names and values.
• terms: a list of IDs of the terms for posts.

Object Date Filter

There are two ways to specify the publication date filter: using exact date/time elements or using from/to range of dates.

DateTime Elements

In this case, the date needs to be sate to an array of elements (note that this array belongs to date element, so there are date inside date here) with values for year, month, day, hour, minute and second. Any of these can be omitted, so if you specify year and day only, all posts that are published on that year and on that day (in any month) will be used.

'object' => array(
  'date' => array(
    'date' => array(
      'year' => 2018,
      'day' => 15
    )
  )
)

DateTime Range

Date is defined by from and to values, both can be timestamps or parsable dates.

'object' => array(
  'date' => array(
    'from' => '2018-01-01 15:00:00',
    'to' => '2018-06-04 00:00:00'
  )
)

Usage Examples

Here are a few examples for the query object.

// Get top 10 thumbs rating posts ordered by UP ratings
$args = array(
  'method' => 'thumbs-rating',
  'limit' => 10,
  'orderby' => 'up',
  'entity' => 'posts',
  'name' => 'post'
);
$ratings = new gdrts_core_query();
$results = $ratings->run($args);

// Get top 5 thumbs rating posts, by selected authors and with listed terms
$args = array(
  'method' => 'thumbs-rating',
  'entity' => 'posts',
  'name' => 'post',
  'object' => array(
    'author' => array(1, 3, 10),
    'terms' => array(5, 7, 53)
  )
);
$ratings = new gdrts_core_query();
$results = $ratings->run($args);

// Get top 5 stars rating posts, published in the year 2018 by selcted authors
$args = array(
  'method' => 'stars-rating',
  'entity' => 'posts',
  'name' => 'post',
  'object' => array(
    'author' => array(1, ),
    'date' => array('date' => array('year' => 2018))
  )
);
$ratings = new gdrts_core_query();
$results = $ratings->run($args);