LLMS_Database_Query
Abstract Database Query Class
Description Description
Source Source
File: includes/abstracts/abstract.llms.database.query.php
abstract class LLMS_Database_Query { /** * Identify the extending query * @var string */ protected $id = 'database'; /** * Arguments * Original merged into defaults * @var array */ protected $arguments = array(); /** * Default arguments before merging with original * @var array */ protected $arguments_default = array(); /** * Original args before merging with defaults * @var array */ protected $arguments_original = array(); /** * Total number of results matching query parameters * @var integer */ public $found_results = 0; /** * Maximum number of pages of results * based off per_page & found_results * @var integer */ public $max_pages = 0; /** * Number of results on the current page * @var integer */ public $number_results = 0; /** * Array of query variables * @var array */ public $query_vars = array(); /** * Array of results retrieved by the query * @var array */ public $results = array(); /** * The raw SQL query * @var string */ protected $sql = ''; /** * Constructor * @param array $args query arguments * @since 3.8.0 * @version 3.8.0 */ public function __construct( $args = array() ) { $this->arguments_original = $args; $this->arguments_default = $this->get_default_args(); $this->setup_args(); $this->query(); } /** * Escape and add quotes to a string, useful for array mapping when building queries * @param mixed $input input data * @return string * @since 3.8.0 * @version 3.8.0 */ public function escape_and_quote_string( $input ) { return "'" . esc_sql( $input ) . "'"; } /** * Retrieve a query variable with an optional fallback / default * @param string $key variable key * @param mixed $default default value * @return mixed * @since 3.8.0 * @version 3.8.0 */ public function get( $key, $default = '' ) { if ( isset( $this->query_vars[ $key ] ) ) { return $this->query_vars[ $key ]; } return $default; } /** * Retrieve default arguments for a the query * @return array * @since 3.8.0 * @version 3.8.0 */ protected function get_default_args() { $args = array( 'page' => 1, 'per_page' => 25, 'search' => '', 'sort' => array( 'id' => 'ASC', ), 'suppress_filters' => false, ); if ( $this->get( 'suppress_filters' ) ) { return $args; } return apply_filters( 'llms_db_query_get_default_args', $args ); } /** * Get a string used as filter names unique to the extending query * @param string $filter filter name * @return string * @since 3.8.0 * @version 3.8.0 */ protected function get_filter( $filter ) { return 'llms_' . $this->id . '_query_' . $filter; } /** * Retrieve an array of results for the given query * @return array * @since 3.8.0 * @version 3.8.0 */ public function get_results() { if ( $this->get( 'suppress_filters' ) ) { return $this->results; } return apply_filters( $this->get_filter( 'get_results' ), $this->results ); } /** * Get the number of results to skip for the query * based on the current page and per_page vars * @return int * @since 3.8.0 * @version 3.8.0 */ protected function get_skip() { return absint( ( $this->get( 'page' ) - 1 ) * $this->get( 'per_page' ) ); } /** * Determine if the query has at least one result * @return bool * @since 3.16.0 * @version 3.16.0 */ public function has_results() { return ( $this->number_results > 0 ); } /** * Determine if we're on the first page of results * @return boolean * @since 3.8.0 * @version 3.14.0 */ 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. * * @return boolean */ public function is_last_page() { return ! $this->has_results() || ( absint( $this->get( 'page' ) ) === $this->max_pages ); } /** * Parse arguments needed for the query * @return void * @since 3.8.0 * @version 3.8.0 */ abstract protected function parse_args(); /** * Prepare the SQL for the query * @return void * @since 3.8.0 * @version 3.8.0 */ abstract protected function preprare_query(); /** * Execute a query * @return void * @since 3.8.0 * @version 3.8.0 */ public function query() { global $wpdb; $this->sql = $this->preprare_query(); if ( ! $this->get( 'suppress_filters' ) ) { $this->sql = apply_filters( $this->get_filter( 'prepare_query' ), $this->sql, $this ); } $this->results = $wpdb->get_results( $this->sql ); $this->number_results = count( $this->results ); $this->set_found_results(); } /** * Sanitize input to ensure an array of absints * @param mixed $ids String/Int or array of strings/ints * @return array * @since 3.15.0 * @version 3.24.0 */ protected function sanitize_id_array( $ids = array() ) { if ( empty( $ids ) ) { $ids = array(); } // allow numeric strings & ints to be passed instead of an array if ( ! is_array( $ids ) && is_numeric( $ids ) && $ids > 0 ) { $ids = array( $ids ); } foreach ( $ids as $key => &$id ) { $id = absint( $id ); // verify we have ints if ( $id <= 0 ) { // remove anything negative or 0 unset( $ids[ $key ] ); } } return $ids; } /** * Sets a query variable * @param string $key variable key * @param mixed $val variable value * @return void * @since 3.8.0 * @version 3.8.0 */ public function set( $key, $val ) { $this->query_vars[ $key ] = $val; } /** * Set variables related to total number of results and pages possible * with supplied arguments * @return void * @since 3.8.0 * @version 3.8.0 */ protected function set_found_results() { global $wpdb; // if no results bail early b/c no reason to calculate anything if ( ! $this->number_results ) { return; } $this->found_results = absint( $wpdb->get_var( 'SELECT FOUND_ROWS()' ) ); $this->max_pages = absint( ceil( $this->found_results / $this->get( 'per_page' ) ) ); } /** * Setup arguments prior to a query * @return void * @since 3.8.0 * @version 3.8.0 */ protected function setup_args() { $this->arguments = wp_parse_args( $this->arguments_original, $this->arguments_default ); $this->parse_args(); foreach ( $this->arguments as $arg => $val ) { $this->set( $arg, $val ); } } /** * Retrieve the prepared SQL for the LIMIT clause * @return string * @since 3.16.0 * @version 3.16.0 */ protected function sql_limit() { global $wpdb; $sql = $wpdb->prepare( 'LIMIT %d, %d', $this->get_skip(), $this->get( 'per_page' ) ); return apply_filters( $this->get_filter( 'limit' ), $sql, $this ); } /** * Retrieve the prepared SQL for the ORDER clause * @return string * @since 3.8.0 * @version 3.8.0 */ protected function sql_orderby() { $sql = 'ORDER BY'; $comma = false; foreach ( $this->get( 'sort' ) as $orderby => $order ) { $pre = ( $comma ) ? ', ' : ' '; $sql .= $pre . "{$orderby} {$order}"; $comma = true; } if ( $this->get( 'suppress_filters' ) ) { return $sql; } return apply_filters( $this->get_filter( 'orderby' ), $sql, $this ); } }
Expand full source code Collapse full source code View on GitHub
Changelog Changelog
Version | Description |
---|---|
3.8.0 | |
3.30.3 | Introduced. |
Methods Methods
- __construct — Constructor
- escape_and_quote_string — Escape and add quotes to a string, useful for array mapping when building queries
- get — Retrieve a query variable with an optional fallback / default
- get_default_args — Retrieve default arguments for a the query
- get_filter — Get a string used as filter names unique to the extending query
- get_results — Retrieve an array of results for the given query
- get_skip — Get the number of results to skip for the query based on the current page and per_page vars
- 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
- preprare_query — Prepare the SQL for the query
- query — Execute a query
- sanitize_id_array — Sanitize input to ensure an array of absints
- set — Sets a query variable
- set_found_results — Set variables related to total number of results and pages possible with supplied arguments
- setup_args — Setup arguments prior to a query
- sql_limit — Retrieve the prepared SQL for the LIMIT clause
- sql_orderby — Retrieve the prepared SQL for the ORDER clause
User Contributed Notes User Contributed Notes
Permalink: