[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/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):
  __construct()
  sanitize_query()
  is_first_order_clause()
  get_compare()
  validate_date_values()
  validate_column()
  get_sql()
  get_sql_clauses()
  get_sql_for_query()
  get_sql_for_subquery()
  get_sql_for_clause()
  build_value()
  build_mysql_datetime()
  build_time_query()


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

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`.

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

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.

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

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

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

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.

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

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.

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

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

return: string MySQL WHERE clause.
since: 3.7.0

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.

return: string[] {
since: 4.1.0

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.

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

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.

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

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

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

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

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

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

return: string|false A MySQL format date/time or false on failure
since: 3.7.0
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

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.

return: string|false A query part or false on failure.
since: 3.7.0
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).



Generated: Tue Oct 8 01:00:02 2024 Cross-referenced by PHPXref 0.7.1