<?php

/**

 * Comment API: WP_Comment_Query class

 *

 * @package WordPress

 * @subpackage Comments

 * @since 4.4.0

 */

/**

 * Core class used for querying comments.

 *

 * @since 3.1.0

 *

 * @see WP_Comment_Query::__construct() for accepted arguments.

 */

class WP_Comment_Query {

	/**

	 * SQL for database query.

	 *

	 * @since 4.0.1

	 * @var string

	 */

	public $request;

	/**

	 * Metadata query container

	 *

	 * @since 3.5.0

	 * @var object WP_Meta_Query

	 */

	public $meta_query = false;

	/**

	 * Metadata query clauses.

	 *

	 * @since 4.4.0

	 * @var array

	 */

	protected $meta_query_clauses;

	/**

	 * SQL query clauses.

	 *

	 * @since 4.4.0

	 * @var array

	 */

	protected $sql_clauses = array(

		'select'  => '',

		'from'    => '',

		'where'   => array(),

		'groupby' => '',

		'orderby' => '',

		'limits'  => '',

	);

	/**

	 * SQL WHERE clause.

	 *

	 * Stored after the {@see 'comments_clauses'} filter is run on the compiled WHERE sub-clauses.

	 *

	 * @since 4.4.2

	 * @var string

	 */

	protected $filtered_where_clause;

	/**

	 * Date query container

	 *

	 * @since 3.7.0

	 * @var object WP_Date_Query

	 */

	public $date_query = false;

	/**

	 * Query vars set by the user.

	 *

	 * @since 3.1.0

	 * @var array

	 */

	public $query_vars;

	/**

	 * Default values for query vars.

	 *

	 * @since 4.2.0

	 * @var array

	 */

	public $query_var_defaults;

	/**

	 * List of comments located by the query.

	 *

	 * @since 4.0.0

	 * @var array

	 */

	public $comments;

	/**

	 * The amount of found comments for the current query.

	 *

	 * @since 4.4.0

	 * @var int

	 */

	public $found_comments = 0;

	/**

	 * The number of pages.

	 *

	 * @since 4.4.0

	 * @var int

	 */

	public $max_num_pages = 0;

	/**

	 * Make private/protected methods readable for backward compatibility.

	 *

	 * @since 4.0.0

	 *

	 * @param string   $name      Method to call.

	 * @param array    $arguments Arguments to pass when calling.

	 * @return mixed|false Return value of the callback, false otherwise.

	 */

	public function __call( $name, $arguments ) {

		if ( 'get_search_sql' === $name ) {

			return call_user_func_array( array( $this, $name ), $arguments );

		}

		return false;

	}

	/**

	 * Constructor.

	 *

	 * Sets up the comment query, based on the query vars passed.

	 *

	 * @since 4.2.0

	 * @since 4.4.0 `$parent__in` and `$parent__not_in` were added.

	 * @since 4.4.0 Order by `comment__in` was added. `$update_comment_meta_cache`, `$no_found_rows`,

	 *              `$hierarchical`, and `$update_comment_post_cache` were added.

	 * @since 4.5.0 Introduced the `$author_url` argument.

	 * @since 4.6.0 Introduced the `$cache_domain` argument.

	 * @since 4.9.0 Introduced the `$paged` argument.

	 *

	 * @param string|array $query {

	 *     Optional. Array or query string of comment query parameters. Default empty.

	 *

	 *     @type string       $author_email              Comment author email address. Default empty.

	 *     @type string       $author_url                Comment author URL. Default empty.

	 *     @type array        $author__in                Array of author IDs to include comments for. Default empty.

	 *     @type array        $author__not_in            Array of author IDs to exclude comments for. Default empty.

	 *     @type array        $comment__in               Array of comment IDs to include. Default empty.

	 *     @type array        $comment__not_in           Array of comment IDs to exclude. Default empty.

	 *     @type bool         $count                     Whether to return a comment count (true) or array of

	 *                                                   comment objects (false). Default false.

	 *     @type array        $date_query                Date query clauses to limit comments by. See WP_Date_Query.

	 *                                                   Default null.

	 *     @type string       $fields                    Comment fields to return. Accepts 'ids' for comment IDs

	 *                                                   only or empty for all fields. Default empty.

	 *     @type int          $ID                        Currently unused.

	 *     @type array        $include_unapproved        Array of IDs or email addresses of users whose unapproved

	 *                                                   comments will be returned by the query regardless of

	 *                                                   `$status`. Default empty.

	 *     @type int          $karma                     Karma score to retrieve matching comments for.

	 *                                                   Default empty.

	 *     @type string       $meta_key                  Include comments with a matching comment meta key.

	 *                                                   Default empty.

	 *     @type string       $meta_value                Include comments with a matching comment meta value.

	 *                                                   Requires `$meta_key` to be set. Default empty.

	 *     @type array        $meta_query                Meta query clauses to limit retrieved comments by.

	 *                                                   See WP_Meta_Query. Default empty.

	 *     @type int          $number                    Maximum number of comments to retrieve.

	 *                                                   Default empty (no limit).

	 *     @type int          $paged                     When used with $number, defines the page of results to return.

	 *                                                   When used with $offset, $offset takes precedence. Default 1.

	 *     @type int          $offset                    Number of comments to offset the query. Used to build

	 *                                                   LIMIT clause. Default 0.

	 *     @type bool         $no_found_rows             Whether to disable the `SQL_CALC_FOUND_ROWS` query.

	 *                                                   Default: true.

	 *     @type string|array $orderby                   Comment status or array of statuses. To use 'meta_value'

	 *                                                   or 'meta_value_num', `$meta_key` must also be defined.

	 *                                                   To sort by a specific `$meta_query` clause, use that

	 *                                                   clause's array key. Accepts 'comment_agent',

	 *                                                   'comment_approved', 'comment_author',

	 *                                                   'comment_author_email', 'comment_author_IP',

	 *                                                   'comment_author_url', 'comment_content', 'comment_date',

	 *                                                   'comment_date_gmt', 'comment_ID', 'comment_karma',

	 *                                                   'comment_parent', 'comment_post_ID', 'comment_type',

	 *                                                   'user_id', 'comment__in', 'meta_value', 'meta_value_num',

	 *                                                   the value of $meta_key, and the array keys of

	 *                                                   `$meta_query`. Also accepts false, an empty array, or

	 *                                                   'none' to disable `ORDER BY` clause.

	 *                                                   Default: 'comment_date_gmt'.

	 *     @type string       $order                     How to order retrieved comments. Accepts 'ASC', 'DESC'.

	 *                                                   Default: 'DESC'.

	 *     @type int          $parent                    Parent ID of comment to retrieve children of.

	 *                                                   Default empty.

	 *     @type array        $parent__in                Array of parent IDs of comments to retrieve children for.

	 *                                                   Default empty.

	 *     @type array        $parent__not_in            Array of parent IDs of comments *not* to retrieve

	 *                                                   children for. Default empty.

	 *     @type array        $post_author__in           Array of author IDs to retrieve comments for.

	 *                                                   Default empty.

	 *     @type array        $post_author__not_in       Array of author IDs *not* to retrieve comments for.

	 *                                                   Default empty.

	 *     @type int          $post_ID                   Currently unused.

	 *     @type int          $post_id                   Limit results to those affiliated with a given post ID.

	 *                                                   Default 0.

	 *     @type array        $post__in                  Array of post IDs to include affiliated comments for.

	 *                                                   Default empty.

	 *     @type array        $post__not_in              Array of post IDs to exclude affiliated comments for.

	 *                                                   Default empty.

	 *     @type int          $post_author               Post author ID to limit results by. Default empty.

	 *     @type string|array $post_status               Post status or array of post statuses to retrieve

	 *                                                   affiliated comments for. Pass 'any' to match any value.

	 *                                                   Default empty.

	 *     @type string       $post_type                 Post type or array of post types to retrieve affiliated

	 *                                                   comments for. Pass 'any' to match any value. Default empty.

	 *     @type string       $post_name                 Post name to retrieve affiliated comments for.

	 *                                                   Default empty.

	 *     @type int          $post_parent               Post parent ID to retrieve affiliated comments for.

	 *                                                   Default empty.

	 *     @type string       $search                    Search term(s) to retrieve matching comments for.

	 *                                                   Default empty.

	 *     @type string|array $status                    Comment stati to limit results by. Accepts an array

	 *                                                   or space/comma-separated list of 'hold' (`comment_status=0`),

	 *                                                   'approve' (`comment_status=1`), 'all', or a custom

	 *                                                   comment status. Default 'all'.

	 *     @type string|array $type                      Include comments of a given type, or array of types.

	 *                                                   Accepts 'comment', 'pings' (includes 'pingback' and

	 *                                                   'trackback'), or anycustom type string. Default empty.

	 *     @type array        $type__in                  Include comments from a given array of comment types.

	 *                                                   Default empty.

	 *     @type array        $type__not_in              Exclude comments from a given array of comment types.

	 *                                                   Default empty.

	 *     @type int          $user_id                   Include comments for a specific user ID. Default empty.

	 *     @type bool|string  $hierarchical              Whether to include comment descendants in the results.

	 *                                                   'threaded' returns a tree, with each comment's children

	 *                                                   stored in a `children` property on the `WP_Comment`

	 *                                                   object. 'flat' returns a flat array of found comments plus

	 *                                                   their children. Pass `false` to leave out descendants.

	 *                                                   The parameter is ignored (forced to `false`) when

	 *                                                   `$fields` is 'ids' or 'counts'. Accepts 'threaded',

	 *                                                   'flat', or false. Default: false.

	 *     @type string       $cache_domain              Unique cache key to be produced when this query is stored in

	 *                                                   an object cache. Default is 'core'.

	 *     @type bool         $update_comment_meta_cache Whether to prime the metadata cache for found comments.

	 *                                                   Default true.

	 *     @type bool         $update_comment_post_cache Whether to prime the cache for comment posts.

	 *                                                   Default false.

	 * }

	 */

	public function __construct( $query = '' ) {

		$this->query_var_defaults = array(

			'author_email'              => '',

			'author_url'                => '',

			'author__in'                => '',

			'author__not_in'            => '',

			'include_unapproved'        => '',

			'fields'                    => '',

			'ID'                        => '',

			'comment__in'               => '',

			'comment__not_in'           => '',

			'karma'                     => '',

			'number'                    => '',

			'offset'                    => '',

			'no_found_rows'             => true,

			'orderby'                   => '',

			'order'                     => 'DESC',

			'paged'                     => 1,

			'parent'                    => '',

			'parent__in'                => '',

			'parent__not_in'            => '',

			'post_author__in'           => '',

			'post_author__not_in'       => '',

			'post_ID'                   => '',

			'post_id'                   => 0,

			'post__in'                  => '',

			'post__not_in'              => '',

			'post_author'               => '',

			'post_name'                 => '',

			'post_parent'               => '',

			'post_status'               => '',

			'post_type'                 => '',

			'status'                    => 'all',

			'type'                      => '',

			'type__in'                  => '',

			'type__not_in'              => '',

			'user_id'                   => '',

			'search'                    => '',

			'count'                     => false,

			'meta_key'                  => '',

			'meta_value'                => '',

			'meta_query'                => '',

			'date_query'                => null, // See WP_Date_Query

			'hierarchical'              => false,

			'cache_domain'              => 'core',

			'update_comment_meta_cache' => true,

			'update_comment_post_cache' => false,

		);

		if ( ! empty( $query ) ) {

			$this->query( $query );

		}

	}

	/**

	 * Parse arguments passed to the comment query with default query parameters.

	 *

	 * @since 4.2.0 Extracted from WP_Comment_Query::query().

	 *

	 * @param string|array $query WP_Comment_Query arguments. See WP_Comment_Query::__construct()

	 */

	public function parse_query( $query = '' ) {

		if ( empty( $query ) ) {

			$query = $this->query_vars;

		}

		$this->query_vars = wp_parse_args( $query, $this->query_var_defaults );

		/**

		 * Fires after the comment query vars have been parsed.

		 *

		 * @since 4.2.0

		 *

		 * @param WP_Comment_Query $this The WP_Comment_Query instance (passed by reference).

		 */

		do_action_ref_array( 'parse_comment_query', array( &$this ) );

	}

	/**

	 * Sets up the WordPress query for retrieving comments.

	 *

	 * @since 3.1.0

	 * @since 4.1.0 Introduced 'comment__in', 'comment__not_in', 'post_author__in',

	 *              'post_author__not_in', 'author__in', 'author__not_in', 'post__in',

	 *              'post__not_in', 'include_unapproved', 'type__in', and 'type__not_in'

	 *              arguments to $query_vars.

	 * @since 4.2.0 Moved parsing to WP_Comment_Query::parse_query().

	 *

	 * @param string|array $query Array or URL query string of parameters.

	 * @return array|int List of comments, or number of comments when 'count' is passed as a query var.

	 */

	public function query( $query ) {

		$this->query_vars = wp_parse_args( $query );

		return $this->get_comments();

	}

	/**

	 * Get a list of comments matching the query vars.

	 *

	 * @since 4.2.0

	 *

	 * @global wpdb $wpdb WordPress database abstraction object.

	 *

	 * @return int|array List of comments or number of found comments if `$count` argument is true.

	 */

	public function get_comments() {

		global $wpdb;

		$this->parse_query();

		// Parse meta query

		$this->meta_query = new WP_Meta_Query();

		$this->meta_query->parse_query_vars( $this->query_vars );

		/**

		 * Fires before comments are retrieved.

		 *

		 * @since 3.1.0

		 *

		 * @param WP_Comment_Query $this Current instance of WP_Comment_Query (passed by reference).

		 */

		do_action_ref_array( 'pre_get_comments', array( &$this ) );

		// Reparse query vars, in case they were modified in a 'pre_get_comments' callback.

		$this->meta_query->parse_query_vars( $this->query_vars );

		if ( ! empty( $this->meta_query->queries ) ) {

			$this->meta_query_clauses = $this->meta_query->get_sql( 'comment', $wpdb->comments, 'comment_ID', $this );

		}

		/*

		 * Only use the args defined in the query_var_defaults to compute the key,

		 * but ignore 'fields', which does not affect query results.

		 */

		$_args = wp_array_slice_assoc( $this->query_vars, array_keys( $this->query_var_defaults ) );

		unset( $_args['fields'] );

		$key          = md5( serialize( $_args ) );

		$last_changed = wp_cache_get_last_changed( 'comment' );

		$cache_key   = "get_comments:$key:$last_changed";

		$cache_value = wp_cache_get( $cache_key, 'comment' );

		if ( false === $cache_value ) {

			$comment_ids = $this->get_comment_ids();

			if ( $comment_ids ) {

				$this->set_found_comments();

			}

			$cache_value = array(

				'comment_ids'    => $comment_ids,

				'found_comments' => $this->found_comments,

			);

			wp_cache_add( $cache_key, $cache_value, 'comment' );

		} else {

			$comment_ids          = $cache_value['comment_ids'];

			$this->found_comments = $cache_value['found_comments'];

		}

		if ( $this->found_comments && $this->query_vars['number'] ) {

			$this->max_num_pages = ceil( $this->found_comments / $this->query_vars['number'] );

		}

		// If querying for a count only, there's nothing more to do.

		if ( $this->query_vars['count'] ) {

			// $comment_ids is actually a count in this case.

			return intval( $comment_ids );

		}

		$comment_ids = array_map( 'intval', $comment_ids );

		if ( 'ids' == $this->query_vars['fields'] ) {

			$this->comments = $comment_ids;

			return $this->comments;

		}

		_prime_comment_caches( $comment_ids, $this->query_vars['update_comment_meta_cache'] );

		// Fetch full comment objects from the primed cache.

		$_comments = array();

		foreach ( $comment_ids as $comment_id ) {

			if ( $_comment = get_comment( $comment_id ) ) {

				$_comments[] = $_comment;

			}

		}

		// Prime comment post caches.

		if ( $this->query_vars['update_comment_post_cache'] ) {

			$comment_post_ids = array();

			foreach ( $_comments as $_comment ) {

				$comment_post_ids[] = $_comment->comment_post_ID;

			}

			_prime_post_caches( $comment_post_ids, false, false );

		}

		/**

		 * Filters the comment query results.

		 *

		 * @since 3.1.0

		 *

		 * @param WP_Comment[]     $_comments An array of comments.

		 * @param WP_Comment_Query $this      Current instance of WP_Comment_Query (passed by reference).

		 */

		$_comments = apply_filters_ref_array( 'the_comments', array( $_comments, &$this ) );