[ Index ]

PHP Cross Reference of WordPress




/wp-includes/ -> class-wp-date-query.php (summary)

(no description)

File Size: 1043 lines (35 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

WP_Date_Query:: (14 methods):

Class: WP_Date_Query  - X-Ref

Class for generating SQL clauses that filter a primary query according to date.

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().

__construct( $date_query, $default_column = 'post_date' )   X-Ref

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.

param: array  $date_query {
param: string $default_column Optional. Default column to query against. See WP_Date_Query::validate_column()
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.

sanitize_query( $queries, $parent_query = null )   X-Ref
Recursive-friendly query sanitizer.

Ensures that each query-level clause has a 'relation' key, and that
each first-order clause contains all the necessary keys from `$defaults`.

param: array $queries
param: array $parent_query
since: 4.1.0
return: array Sanitized queries.

is_first_order_clause( $query )   X-Ref
Determine whether this is a first-order clause.

Checks to see if the current clause has any time-related keys.
If so, it's first-order.

param: array $query Query clause.
since: 4.1.0
return: bool True if this is a first-order clause.

get_compare( $query )   X-Ref
Determines and validates what comparison operator to use.

param: array $query A date query or a date subquery.
since: 3.7.0
return: string The comparison operator.

validate_date_values( $date_query = array()   X-Ref
Validates the given date_query values and triggers errors if something is not valid.

Note that date queries with invalid date ranges are allowed to
continue (though of course no items will be found for impossible dates).
This method only generates debug notices for these cases.

param: array $date_query The date_query array.
since: 4.1.0
return: bool  True if all values in the query are valid, false if one or more fail.

validate_column( $column )   X-Ref
Validates a column name parameter.

Column names without a table prefix (like 'post_date') are checked against a list of
allowed and known tables, and then, if found, have a table prefix (such as 'wp_posts.')
prepended. Prefixed column names (such as 'wp_posts.post_date') bypass this allowed
check, and are only sanitized to remove illegal characters.

param: string $column The user-supplied column name.
since: 3.7.0
return: string A validated column name value.

get_sql()   X-Ref
Generate WHERE clause to be appended to a main query.

since: 3.7.0
return: string MySQL WHERE clause.

get_sql_clauses()   X-Ref
Generate SQL clauses to be appended to a main query.

Called by the public WP_Date_Query::get_sql(), this method is abstracted
out to maintain parity with the other Query classes.

since: 4.1.0
return: string[] {

get_sql_for_query( $query, $depth = 0 )   X-Ref
Generate SQL clauses for a single query array.

If nested subqueries are found, this method recurses the tree to
produce the properly nested SQL.

param: array $query Query to parse.
param: int   $depth Optional. Number of tree levels deep we currently are.
since: 4.1.0
return: array {

get_sql_for_subquery( $query )   X-Ref
Turns a single date clause into pieces for a WHERE clause.

A wrapper for get_sql_for_clause(), included here for backward
compatibility while retaining the naming convention across Query classes.

param: array $query Date query arguments.
since: 3.7.0
return: string[] {

get_sql_for_clause( $query, $parent_query )   X-Ref
Turns a first-order date query into SQL for a WHERE clause.

param: array $query        Date query clause.
param: array $parent_query Parent query of the current date query.
since: 4.1.0
return: string[] {

build_value( $compare, $value )   X-Ref
Builds and validates a value string based on the comparison operator.

param: string       $compare The compare operator to use.
param: string|array $value   The value.
since: 3.7.0
return: string|false|int The value to be used in SQL or false on error.

build_mysql_datetime( $datetime, $default_to_max = false )   X-Ref
Builds a MySQL format date/time based on some query parameters.

You can pass an array of values (year, month, etc.) with missing parameter values being defaulted to
either the maximum or minimum values (controlled by the $default_to parameter). Alternatively you can
pass a string that will be passed to date_create().

param: string|array $datetime       An array of parameters or a strotime() string
param: bool         $default_to_max Whether to round up incomplete dates. Supported by values
since: 3.7.0
return: string|false A MySQL format date/time or false on failure

build_time_query( $column, $compare, $hour = null, $minute = null, $second = null )   X-Ref
Builds a query string for comparing time values (hour, minute, second).

If just hour, minute, or second is set than a normal comparison will be done.
However if multiple values are passed, a pseudo-decimal time will be created
in order to be able to accurately compare against.

param: string   $column  The column to query against. Needs to be pre-validated!
param: string   $compare The comparison operator. Needs to be pre-validated!
param: int|null $hour    Optional. An hour value (0-23).
param: int|null $minute  Optional. A minute value (0-59).
param: int|null $second  Optional. A second value (0-59).
since: 3.7.0
return: string|false A query part or false on failure.

Generated: Mon Aug 15 01:00:02 2022 Cross-referenced by PHPXref 0.7.1