WordPress.org

Make WordPress Core

Changeset 31336


Ignore:
Timestamp:
02/05/2015 06:16:35 AM (7 years ago)
Author:
DrewAPicture
Message:

Clarify inline documentation for WP_Date_Query to better explain the relationship between an individual clause's 'compare' argument and various integer-based date arguments.

If the 'compare' argument equals 'IN' or 'NOT IN', arrays of any number of specific, valid values are accepted and simply considered based on the value of 'operator' (OR or AND). If the 'compare' argument is a range such as 'BETWEEN' or 'NOT BETWEEN', arrays of only two valid values are accepted.

Props boonebgorges.
Fixes #31036.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/date.php

    r31251 r31336  
    6666     * Constructor.
    6767     *
     68     * Time-related parameters that normally require integer values ('year', 'month', 'week', 'dayofyear', 'day',
     69     * 'dayofweek', 'dayofweek_iso', 'hour', 'minute', 'second') accept arrays of integers for some values of
     70     * 'compare'. When 'compare' is 'IN' or 'NOT IN', arrays are accepted; when 'compare' is 'BETWEEN' or 'NOT
     71     * BETWEEN', arrays of two valid values are required. See individual argument descriptions for accepted values.
     72     *
    6873     * @since 3.7.0
    6974     * @since 4.0.0 The $inclusive logic was updated to include all times within the date range.
     
    7681     *     @type array {
    7782     *         @type string $column   Optional. The column to query against. If undefined, inherits the value of
    78      *                                the $default_column parameter. Default 'post_date'. Accepts 'post_date',
    79      *                                'post_date_gmt', 'post_modified','post_modified_gmt', 'comment_date',
    80      *                                'comment_date_gmt'.
    81      *         @type string $compare  Optional. The comparison operator. Default '='.
    82      *                                Accepts '=', '!=', '>', '>=', '<', '<=', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'.
    83      *         @type string $relation Optional. The boolean relationship between the date queries. Default 'OR'.
    84      *                                Accepts 'OR', 'AND'.
     83     *                                the `$default_column` parameter. Accepts 'post_date', 'post_date_gmt',
     84     *                                'post_modified','post_modified_gmt', 'comment_date', 'comment_date_gmt'.
     85     *                                Default 'post_date'.
     86     *         @type string $compare  Optional. The comparison operator. Accepts '=', '!=', '>', '>=', '<', '<=',
     87     *                                'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. Default '='.
     88     *         @type string $relation Optional. The boolean relationship between the date queries. Accepts 'OR' or 'AND'.
     89     *                                Default 'OR'.
    8590     *         @type array {
    8691     *             Optional. An array of first-order clause parameters, or another fully-formed date query.
    8792     *
    88      *             @type string|array $before Optional. Date to retrieve posts before. Accepts strtotime()-compatible
    89      *                                        string, or array of 'year', 'month', 'day' values. {
     93     *             @type string|array $before {
     94     *                 Optional. Date to retrieve posts before. Accepts `strtotime()`-compatible string,
     95     *                 or array of 'year', 'month', 'day' values.
    9096     *
    9197     *                 @type string $year  The four-digit year. Default empty. Accepts any four-digit year.
     
    95101     *                                     Default (string:empty)|(array:1). Accepts numbers 1-31.
    96102     *             }
    97      *             @type string|array $after Optional. Date to retrieve posts after. Accepts strtotime()-compatible
    98      *                                       string, or array of 'year', 'month', 'day' values. {
    99      *
    100      *                 @type string $year  The four-digit year. Default empty. Accepts any four-digit year.
    101      *                 @type string $month Optional when passing array.The month of the year.
    102      *                                     Default (string:empty)|(array:12). Accepts numbers 1-12.
    103      *                 @type string $day   Optional when passing array.The day of the month.
    104      *                                     Default (string:empty)|(array:last day of month). Accepts numbers 1-31.
     103     *             @type string|array $after {
     104     *                 Optional. Date to retrieve posts after. Accepts `strtotime()`-compatible string,
     105     *                 or array of 'year', 'month', 'day' values.
     106     *
     107     *                 @type string $year  The four-digit year. Accepts any four-digit year. Default empty.
     108     *                 @type string $month Optional when passing array. The month of the year. Accepts numbers 1-12.
     109     *                                     Default (string:empty)|(array:12).
     110     *                 @type string $day   Optional when passing array.The day of the month. Accepts numbers 1-31.
     111     *                                     Default (string:empty)|(array:last day of month).
    105112     *             }
    106      *             @type string       $column    Optional. Used to add a clause comparing a column other than the column
    107      *                                           specified in the top-level $column parameter.  Default is the value
    108      *                                           of top-level $column. Accepts 'post_date', 'post_date_gmt',
    109      *                                           'post_modified', 'post_modified_gmt', 'comment_date', 'comment_date_gmt'.
    110      *             @type string       $compare       Optional. The comparison operator. Default '='.
    111      *                                               Accepts '=', '!=', '>', '>=', '<', '<=', 'IN', 'NOT IN',
    112      *                                               'BETWEEN', 'NOT BETWEEN'.
     113     *             @type string       $column        Optional. Used to add a clause comparing a column other than the
     114     *                                               column specified in the top-level `$column` parameter. Accepts
     115     *                                               'post_date', 'post_date_gmt', 'post_modified', 'post_modified_gmt',
     116     *                                               'comment_date', 'comment_date_gmt'. Default is the value of
     117     *                                               top-level `$column`.
     118     *             @type string       $compare       Optional. The comparison operator. Accepts '=', '!=', '>', '>=',
     119     *                                               '<', '<=', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. 'IN',
     120     *                                               'NOT IN', 'BETWEEN', and 'NOT BETWEEN'. Comparisons support
     121     *                                               arrays in some time-related parameters. Default '='.
    113122     *             @type bool         $inclusive     Optional. Include results from dates specified in 'before' or
    114123     *                                               'after'. Default false.
    115      *             @type int          $year          Optional. The four-digit year number. Default empty. Accepts
    116      *                                               any four-digit year.
    117      *             @type int          $month         Optional. The two-digit month number. Default empty.
    118      *                                               Accepts numbers 1-12.
    119      *             @type int          $week          Optional. The week number of the year. Default empty.
    120      *                                               Accepts numbers 0-53.
    121      *             @type int          $dayofyear     Optional. The day number of the year. Default empty.
    122      *                                               Accepts numbers 1-366.
    123      *             @type int          $day           Optional. The day of the month. Default empty.
    124      *                                               Accepts numbers 1-31.
    125      *             @type int          $dayofweek     Optional. The day number of the week. Default empty.
    126      *                                               Accepts numbers 1-7 (1 is Sunday).
    127      *             @type int          $dayofweek_iso Optional. The day number of the week (ISO). Accepts numbers 1-7
    128      *                                               (1 is Monday). Default empty.
    129      *             @type int          $hour          Optional. The hour of the day. Default empty. Accepts numbers 0-23.
    130      *             @type int          $minute        Optional. The minute of the hour. Default empty. Accepts
    131      *                                               numbers 0-60.
    132      *             @type int          $second        Optional. The second of the minute. Default empty.
    133      *                                               Accepts numbers 0-60.
     124     *             @type int|array    $year          Optional. The four-digit year number. Accepts any four-digit year
     125     *                                               or an array of years if `$compare` supports it. Default empty.
     126     *             @type int|array    $month         Optional. The two-digit month number. Accepts numbers 1-12 or an
     127     *                                               array of valid numbers if `$compare` supports it. Default empty.
     128     *             @type int|array    $week          Optional. The week number of the year. Accepts numbers 0-53 or an
     129     *                                               array of valid numbers if `$compare` supports it. Default empty.
     130     *             @type int|array    $dayofyear     Optional. The day number of the year. Accepts numbers 1-366 or an
     131     *                                               array of valid numbers if `$compare` supports it.
     132     *             @type int|array    $day           Optional. The day of the month. Accepts numbers 1-31 or an array
     133     *                                               of valid numbers if `$compare` supports it. Default empty.
     134     *             @type int|array    $dayofweek     Optional. The day number of the week. Accepts numbers 1-7 (1 is
     135     *                                               Sunday) or an array of valid numbers if `$compare` supports it.
     136     *                                               Default empty.
     137     *             @type int|array    $dayofweek_iso Optional. The day number of the week (ISO). Accepts numbers 1-7
     138     *                                               (1 is Monday) or an array of valid numbers if `$compare` supports it.
     139     *                                               Default empty.
     140     *             @type int|array    $hour          Optional. The hour of the day. Accepts numbers 0-23 or an array
     141     *                                               of valid numbers if `$compare` supports it. Default empty.
     142     *             @type int|array    $minute        Optional. The minute of the hour. Accepts numbers 0-60 or an array
     143     *                                               of valid numbers if `$compare` supports it. Default empty.
     144     *             @type int|array    $second        Optional. The second of the minute. Accepts numbers 0-60 or an
     145     *                                               array of valid numbers if `$compare` supports it. Default empty.
    134146     *         }
    135147     *     }
Note: See TracChangeset for help on using the changeset viewer.