WP_Date_Query
- Since
- 3.7.0
- Source
wp-includes/class-wp-date-query.php:17
Class for generating SQL clauses that filter a primary query according to date.
Description
WP_Date_Query is a helper that allows primary query classes, such as WP_Query, to filter their results by date columns, by generating WHERE subclauses to be attached to the primary SQL query string.
Attempting to filter by an invalid date value (eg month=13) will generate SQL that will return no results. In these cases, a _doing_it_wrong() error notice is also thrown.
See WP_Date_Query::validate_date_values().
Compatibility
- WordPress
- since 3.7.0
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0).
Hooks and filters fired · 2
Every hook that fires from inside WP_Date_Query, in the order it appears in the class, grouped by the method that fires it.
WP_Date_Query::get_sql()
- apply_filters( get_date_sql )filter line 573
Properties · 5
$queriesarraypublic- Array of date queries.
$relationstringpublic- The default relation between top-level queries. Can be either 'AND' or 'OR'.
$columnstringpublic- The column to query against. Can be changed via the query arguments.
$comparestringpublic- The value comparison operator. Can be changed via the query arguments.
$time_keysstring[]public- Supported time-related parameter keys.
Methods · 15
- __construct()Constructor.
- sanitize_query()Recursive-friendly query sanitizer.
- is_first_order_clause()Determines whether this is a first-order clause.
- get_compare()Determines and validates what comparison operator to use.
- validate_date_values()Validates the given date_query values and triggers errors if something is not valid.
- validate_column()Validates a column name parameter.
- get_sql()Generates WHERE clause to be appended to a main query.
- get_sql_clauses()Generates SQL clauses to be appended to a main query.
- get_sql_for_query()Generates SQL clauses for a single query array.
- get_sql_for_subquery()Turns a single date clause into pieces for a WHERE clause.
- get_sql_for_clause()Turns a first-order date query into SQL for a WHERE clause.
- build_value()Builds and validates a value string based on the comparison operator.
- build_mysql_datetime()Builds a MySQL format date/time based on some query parameters.
- build_time_query()Builds a query string for comparing time values (hour, minute, second).
- sanitize_relation()Sanitizes a 'relation' operator.
Source code
#[AllowDynamicProperties]class WP_Date_Query { /** * Array of date queries. * * See WP_Date_Query::__construct() for information on date query arguments. * * @since 3.7.0 * @var array */ public $queries = array(); /** * The default relation between top-level queries. Can be either 'AND' or 'OR'. * * @since 3.7.0 * @var string */ public $relation = 'AND'; /** * The column to query against. Can be changed via the query arguments. * * @since 3.7.0 * @var string */ public $column = 'post_date'; /** * The value comparison operator. Can be changed via the query arguments. * * @since 3.7.0 * @var string */ public $compare = '='; /** * Supported time-related parameter keys. * * @since 4.1.0 * @var string[] */ public $time_keys = array( 'after', 'before', 'year', 'month', 'monthnum', 'week', 'w', 'dayofyear', 'day', 'dayofweek', 'dayofweek_iso', 'hour', 'minute', 'second' ); /** * Constructor. * * Time-related parameters that normally require integer values ('year', 'month', 'week', 'dayofyear', 'day', * 'dayofweek', 'dayofweek_iso', 'hour', 'minute', 'second') accept arrays of integers for some values of * 'compare'. When 'compare' is 'IN' or 'NOT IN', arrays are accepted; when 'compare' is 'BETWEEN' or 'NOT * BETWEEN', arrays of two valid values are required. See individual argument descriptions for accepted values. * * @since 3.7.0 * @since 4.0.0 The $inclusive logic was updated to include all times within the date range. * @since 4.1.0 Introduced 'dayofweek_iso' time type parameter. * * @param array $date_query { * Array of date query clauses. * * @type array ...$0 { * @type string $column Optional. The column to query against. If undefined, inherits the value of * the `$default_column` parameter. See WP_Date_Query::validate_column() and * the {@see 'date_query_valid_columns'} filter for the list of accepted values. * Default 'post_date'. * @type string $compare Optional. The comparison operator. Accepts '=', '!=', '>', '>=', '<', '<=', * 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. Default '='. * @type string $relation Optional. The boolean relationship between the date queries. Accepts 'OR' or 'AND'. * Default 'OR'. * @type array ...$0 { * Optional. An array of first-order clause parameters, or another fully-formed date query. * * @type string|array $before { * Optional. Date to retrieve posts before. Accepts `strtotime()`-compatible string, * or array of 'year', 'month', 'day' values. * * @type string $year The four-digit year. Default empty. Accepts any four-digit year. * @type string $month Optional when passing array. The month of the year. * Default (string:empty)|(array:1). Accepts numbers 1-12. * @type string $day Optional when passing array. The day of the month. * Default (string:empty)|(array:1). Accepts numbers 1-31.Changelog
Introduced in 3.7.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/class-wp-date-query.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.