LLMS_Abstract_Query

Database Query abstract class.

Parameters
Source
Related
- Used By
Methods
Changelog
User Contributed Notes

Parameters Parameters

$page: (int) (Required) Results page number. Default: 1.
$per_page: (int) (Required) Number of results to retrieve per page. Default: 10.
$search: (int) (Required) Text search term or query. Default: ''.
$sort: (int) (Required) Result order and orderby. Default: array().
$suppress_filters: (int) (Required) Whether or not to allow filter hooks to run. Default: false.
$no_found_rows: (int) (Required) Whether or not to disable the total number of found results for the query. Default: false.

Source Source

File: includes/abstracts/llms-abstract-query.php

abstract class LLMS_Abstract_Query {
 
    /**
     * Identify the extending query.
     *
     * @var string
     */
    protected $id = '';
 
    /**
     * Defines fields that can be sorted on via ORDER BY.
     *
     * If this is not defined by extending classes, the sort data
     * will not be validated.
     *
     * @var string[]|null
     */
    protected $allowed_sort_fields = array();
 
    /**
     * Combined arguments prior to sanitization.
     *
     * This is the final resulting arguments used to generate the query,
     * the result of the default arguments merged into the submitted arguments.
     *
     * @var array
     */
    protected $arguments = array();
 
    /**
     * Default arguments before merging with original.
     *
     * @var array
     */
    protected $arguments_default = array();
 
    /**
     * Original arguments before merging with defaults.
     *
     * @var array
     */
    protected $arguments_original = array();
 
    /**
     * Total number of results matching query parameters.
     *
     * @var integer
     */
    protected $found_results = 0;
 
    /**
     * Maximum number of pages of results based off per_page & found_results.
     *
     * @var integer
     */
    protected $max_pages = 0;
 
    /**
     * Number of results on the current page.
     *
     * @var integer
     */
    protected $number_results = 0;
 
    /**
     * The final query used to retrieve results.
     *
     * For a raw database query, this is the SQL passed to `$wpdb->get_results()`. For a WP_Posts query
     * this is the array of query arguments passed into the `WP_Query`. Other extending queries
     * may used this as they see fit.
     *
     * @var mixed
     */
    protected $query = array();
 
    /**
     * The parsed and sanitized arguments ultimately used by the query.
     *
     * @var array
     */
    protected $query_vars = array();
 
    /**
     * Array of results retrieved by the query.
     *
     * @var array
     */
    protected $results = array();
 
    /**
     * Constructor.
     *
     * @since 6.0.0
     *
     * @param array $args Query arguments. When not provided the default arguments will be used.
     * @return void
     */
    public function __construct( $args = array() ) {
 
        $this->arguments_original = $args;
        $this->arguments_default  = $this->get_default_args();
 
        $this->setup_args();
 
        $this->query();
 
    }
 
    /**
     * Set result counts and pagination properties.
     *
     * @since 6.0.0
     *
     * @return void
     */
    protected function count_results() {
 
        $this->number_results = count( (array) $this->results );
 
        // If we have results and found rounds isn't disabled.
        if ( $this->number_results && ! $this->get( 'no_found_rows' ) ) {
            $this->found_results = $this->found_results();
            $this->max_pages     = absint( ceil( $this->found_results / $this->get( 'per_page' ) ) );
        }
 
    }
 
    /**
     * Determines the default arguments for the query.
     *
     * Extending classes can override or extend this method to customize the default query
     * arguments for the query.
     *
     * @since 6.0.0
     *
     * @return array
     */
    protected function default_arguments() {
 
        return array(
            'page'             => 1,
            'per_page'         => 10,
            'search'           => '',
            'sort'             => array(),
            'suppress_filters' => false,
            'no_found_rows'    => false,
        );
 
    }
 
    /**
     * Determines the total number of found results for the given query and returns it.
     *
     * @since 6.0.0
     *
     * @return int
     */
    abstract protected function found_results();
 
    /**
     * Retrieve a query variable with an optional fallback value when the value is not set.
     *
     * @since 3.8.0
     * @since 6.0.0 Moved from `LLMS_Database_Query` and updated to use the null coalesce operator.
     *
     * @param string $key     Variable key.
     * @param mixed  $default Default value.
     * @return mixed
     */
    public function get( $key, $default = '' ) {
        return $this->query_vars[ $key ] ?? $default;
    }
 
    /**
     * Get the final combined arguments used to generate the query.
     *
     * Retrieves the value of the protected `$arguments` variable.
     *
     * @since 6.0.0
     *
     * @return array
     */
    public function get_arguments() {
        return $this->arguments;
    }
 
    /**
     * Get the default arguments used for the query.
     *
     * Retrieves the value of the protected `$arguments_default` variable.
     *
     * @since 6.0.0
     *
     * @return array
     */
    public function get_arguments_default() {
        return $this->arguments_default;
    }
 
    /**
     * Get the original, uncleaned, arguments submitted to the query.
     *
     * Retrieves the value of the protected `$arguments_original` variable.
     *
     * @since 6.0.0
     *
     * @return array
     */
    public function get_arguments_original() {
        return $this->arguments_original;
    }
 
    /**
     * Get the query.
     *
     * Retrieves the value of the protected `$query` variable.
     *
     * @since 6.0.0
     *
     * @return mixed
     */
    public function get_query() {
        return $this->query;
    }
 
    /**
     * Retrieve a list of fields that are allowed to be used for result sorting.
     *
     * @since 6.0.0
     *
     * @return string[]
     */
    protected function get_allowed_sort_fields() {
 
        $allowed_fields = $this->allowed_sort_fields;
 
        if ( $this->get( 'suppress_filters' ) ) {
            return $allowed_fields;
        }
 
        /**
         * Filters the allowed sort fields.
         *
         * The dynamic portion of this hook, `$this->id`, refers to ID of the extending
         * query class.
         *
         * @since 6.0.0
         *
         * @param array $allowed_fields Default arguments.
         */
        return apply_filters( "llms_{$this->id}_query_allowed_sort_fields", $allowed_fields );
 
    }
 
    /**
     * Retrieve default arguments for the query.
     *
     * @since 3.8.0
     * @since 4.5.1 Added new default arg `no_found_rows` set to false.
     * @since 6.0.0 Moved from `LLMS_Database_Query` abstract.
     *
     * @return array
     */
    protected function get_default_args() {
 
        if ( $this->get( 'suppress_filters' ) ) {
            return $this->default_arguments();
        }
 
        /**
         * Filters the query default args.
         * The dynamic part of the filter `$this->id` identifies the extending query.
         *
         * @since 3.8.0
         *
         * @param array $args Array of default arguments to set up the query with.
         */
        return apply_filters( "llms_{$this->id}_query_get_default_args", $this->default_arguments() );
 
    }
 
    /**
     * Get the total results found for the query.
     *
     * If the query was instantiated with `$no_found_rows=true` this will always
     * return `0`.
     *
     * Retrieves the value of the protected property `$found_results`.
     *
     * @since 6.0.0
     *
     * @return int
     */
    public function get_found_results() {
        return $this->found_results;
    }
 
    /**
     * Get the total number of pages available for the given query.
     *
     * If the query was instantiated with `$no_found_rows=true` this will always
     * return `0`.
     *
     * Retrieves the value of the protected property `$max_pages`.
     *
     * @since 6.0.0
     *
     * @return int
     */
    public function get_max_pages() {
        return $this->max_pages;
    }
 
    /**
     * Get the number of results on the current page.
     *
     * Retrieves the value of the protected property `$number_results`.
     *
     * @since 6.0.0
     *
     * @return int
     */
    public function get_number_results() {
        return $this->number_results;
    }
 
    /**
     * Retrieve an array of results for the given query.
     *
     * @since 3.8.0
     * @since 4.5.1 Drop use of `this->get_filter('get_results')` in favor of `"llms_{$this->id}_query_get_results"`.
     * @since 6.0.0 Moved from `LLMS_Database_Query` abstract.
     *
     * @return array
     */
    public function get_results() {
 
        if ( $this->get( 'suppress_filters' ) ) {
            return $this->results;
        }
 
        /**
         * Filters the query results.
         *
         * The dynamic part of the filter `$this->id` identifies the extending query.
         *
         * @since 3.8.0
         *
         * @param array $results Array of results retrieved by the query.
         */
        return apply_filters( "llms_{$this->id}_query_get_results", $this->results );
 
    }
 
    /**
     * Determine if the query has at least one result.
     *
     * @since 3.16.0
     * @since 6.0.0 Moved from `LLMS_Database_Query` abstract.
     *
     * @return bool
     */
    public function has_results() {
        return $this->number_results > 0;
    }
 
    /**
     * Determine if we're on the first page of results.
     *
     * @since 3.8.0
     * @since 3.14.0 Unknown.
     * @since 6.0.0 Moved from `LLMS_Database_Query` abstract.
     *
     * @return boolean
     */
    public function is_first_page() {
        return 1 === absint( $this->get( 'page' ) );
    }
 
    /**
     * Determine if we're on the last page of results.
     *
     * @since 3.8.0
     * @since 3.30.3 Return true if there are no results.
     * @since 6.0.0 Moved from `LLMS_Database_Query` abstract.
     *
     * @return boolean
     */
    public function is_last_page() {
        return ! $this->has_results() || ( absint( $this->get( 'page' ) ) === $this->max_pages );
    }
 
    /**
     * Parse arguments needed for the query.
     *
     * @since 3.8.0
     *
     * @return void
     */
    abstract protected function parse_args();
 
    /**
     * Perform the query and return the results.
     *
     * @since 6.0.0
     *
     * @return array
     */
    abstract protected function perform_query();
 
    /**
     * Prepare the query.
     *
     * Should return the query which will be used by `query()`.
     *
     * @since 6.0.0
     *
     * @return mixed
     */
    abstract protected function prepare_query();
 
    /**
     * Execute a query.
     *
     * @since 3.8.0
     * @since 4.5.1 Drop use of `$this->get_filter('prepare_query')` in favor of `"llms_{$this->id}_query_prepare_query"`.
     * @since 6.0.0 Moved from `LLMS_Database_Query` abstract.
     *
     * @return void
     */
    public function query() {
 
        $this->query = $this->prepare_query();
        if ( ! $this->get( 'suppress_filters' ) ) {
            /**
             * Filters the query SQL.
             *
             * The dynamic part of the filter `$this->id` identifies the extending query.
             *
             * @since 3.8.0
             *
             * @param string              $sql      The SQL query.
             * @param LLMS_Database_Query $db_query The LLMS_Database_Query instance.
             */
            $this->query = apply_filters( "llms_{$this->id}_query_prepare_query", $this->query, $this );
        }
 
        $this->results = $this->perform_query();
 
        $this->count_results();
 
    }
 
    /**
     * Sanitize input to ensure an array of absolute integers.
     *
     * @since 3.15.0
     * @since 3.24.0 Unknown.
     * @since 6.0.0 Moved from `LLMS_Database_Query` abstract.
     *
     * @param string|int|array $ids String/Int or array of strings/ints.
     * @return array
     */
    protected function sanitize_id_array( $ids = array() ) {
 
        if ( empty( $ids ) ) {
            return array();
        }
 
        // Allow numeric strings & ints to be passed instead of an array.
        $ids = ! is_array( $ids ) ? array( $ids ) : $ids;
 
        // Force positive ints.
        $ids = array_map( 'absint', $ids );
 
        // Remove empty values.
        return array_values( array_filter( $ids ) );
 
    }
 
    /**
     * Removes any invalid sort fields before preparing a query.
     *
     * @since 3.34.0
     * @since 6.0.0 Moved from `LLMS_Database_Query`.
     *              Use `get_allowed_sort_fields()`.
     *
     * @return void
     */
    protected function sanitize_sort( $sort ) {
 
        $allowed_fields = $this->get_allowed_sort_fields();
 
        if ( empty( $allowed_fields ) ) {
            return $sort;
        }
 
        foreach ( (array) $sort as $orderby => $order ) {
            if ( ! in_array( $orderby, $allowed_fields, true ) || ! in_array( $order, array( 'ASC', 'DESC' ), true ) ) {
                unset( $sort[ $orderby ] );
            }
        }
 
        return $sort;
 
    }
 
    /**
     * Sets a query variable.
     *
     * @since 3.8.0
     * @since 6.0.0 Moved from `LLMS_Database_Query` abstract.
     *
     * @param string $key Variable key.
     * @param mixed  $val Variable value.
     * @return void
     */
    public function set( $key, $val ) {
        $this->query_vars[ $key ] = $val;
    }
 
    /**
     * Setup arguments prior to a query.
     *
     * @since 3.8.0
     * @since 3.34.0 Sanitizes sort parameters.
     * @since 4.5.1 Added filter `"llms_{$this->id}_query_parse_args"`.
     * @since 6.0.0 Moved from `LLMS_Database_Query` abstract.
     *
     * @return void
     */
    protected function setup_args() {
 
        $this->arguments = wp_parse_args( $this->arguments_original, $this->arguments_default );
 
        $this->parse_args();
 
        if ( ! $this->get( 'suppress_filters' ) ) {
            /**
             * Filters the parsed query arguments.
             *
             * The dynamic part of the filter `$this->id` identifies the extending query.
             *
             * @since 4.5.1
             *
             * @param array               $ars           The query parse arguments.
             * @param LLMS_Database_Query $db_query      The LLMS_Database_Query instance.
             * @param array               $original_args Original arguments before merging with defaults.
             * @param array               $default_args  Default arguments before merging with original.
             */
            $this->arguments = apply_filters( "llms_{$this->id}_query_parse_args", $this->arguments, $this, $this->arguments_original, $this->arguments_default );
        }
 
        foreach ( $this->arguments as $arg => $val ) {
 
            $val = 'sort' === $arg ? $this->sanitize_sort( $this->arguments['sort'] ) : $val;
            $this->set( $arg, $val );
 
        }
 
    }
 
}

Expand full source code Collapse full source code View on GitHub

Top ↑

Used By Used By

Used By
Used By	Description
includes/abstracts/llms-abstract-posts-query.php: LLMS_Abstract_Posts_Query	Abstract WP_Posts query class.
includes/abstracts/abstract.llms.database.query.php: LLMS_Database_Query	Database Query abstract class.

Top ↑

Methods Methods

__construct — Constructor.
count_results — Set result counts and pagination properties.
default_arguments — Determines the default arguments for the query.
found_results — Determines the total number of found results for the given query and returns it.
get — Retrieve a query variable with an optional fallback value when the value is not set.
get_allowed_sort_fields — Retrieve a list of fields that are allowed to be used for result sorting.
get_arguments — Get the final combined arguments used to generate the query.
get_arguments_default — Get the default arguments used for the query.
get_arguments_original — Get the original, uncleaned, arguments submitted to the query.
get_default_args — Retrieve default arguments for the query.
get_found_results — Get the total results found for the query.
get_max_pages — Get the total number of pages available for the given query.
get_number_results — Get the number of results on the current page.
get_query — Get the query.
get_results — Retrieve an array of results for the given query.
has_results — Determine if the query has at least one result.
is_first_page — Determine if we're on the first page of results.
is_last_page — Determine if we're on the last page of results.
parse_args — Parse arguments needed for the query.
perform_query — Perform the query and return the results.
prepare_query — Prepare the query.
query — Execute a query.
sanitize_id_array — Sanitize input to ensure an array of absolute integers.
sanitize_sort — Removes any invalid sort fields before preparing a query.
set — Sets a query variable.
setup_args — Setup arguments prior to a query.

Top ↑

Changelog Changelog

Changelog
Version	Description
6.0.0	Introduced.

Top ↑

User Contributed Notes User Contributed Notes

You must log in before being able to contribute a note or feedback.

LifterLMS

Code Reference

LLMS_Abstract_Query

Contents

Parameters Parameters

Source Source

Methods Methods

Changelog Changelog

User Contributed Notes User Contributed Notes

LifterLMS

LLMS_Abstract_Query

Contents

Parameters #Parameters

Source #Source

Related #Related

Used By #Used By

Methods #Methods

Changelog #Changelog

User Contributed Notes #User Contributed Notes

Parameters Parameters

Source Source

Related Related

Used By Used By

Methods Methods

Changelog Changelog

User Contributed Notes User Contributed Notes