<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[31336] trunk/src/wp-includes/date.php: 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.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="https://core.trac.wordpress.org/changeset/31336">31336</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"https://core.trac.wordpress.org/changeset/31336","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>DrewAPicture</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2015-02-05 06:16:35 +0000 (Thu, 05 Feb 2015)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>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 <a href="https://core.trac.wordpress.org/ticket/31036">#31036</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesdatephp">trunk/src/wp-includes/date.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesdatephp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/date.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/date.php 2015-02-05 06:15:59 UTC (rev 31335)
+++ trunk/src/wp-includes/date.php 2015-02-05 06:16:35 UTC (rev 31336)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -65,6 +65,11 @@
</span><span class="cx" style="display: block; padding: 0 10px"> /**
</span><span class="cx" style="display: block; padding: 0 10px"> * Constructor.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * 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.
+ *
</ins><span class="cx" style="display: block; padding: 0 10px"> * @since 3.7.0
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 4.0.0 The $inclusive logic was updated to include all times within the date range.
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 4.1.0 Introduced 'dayofweek_iso' time type parameter.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -75,18 +80,19 @@
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @type array {
</span><span class="cx" style="display: block; padding: 0 10px"> * @type string $column Optional. The column to query against. If undefined, inherits the value of
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * the $default_column parameter. Default 'post_date'. Accepts 'post_date',
- * 'post_date_gmt', 'post_modified','post_modified_gmt', 'comment_date',
- * 'comment_date_gmt'.
- * @type string $compare Optional. The comparison operator. Default '='.
- * Accepts '=', '!=', '>', '>=', '<', '<=', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'.
- * @type string $relation Optional. The boolean relationship between the date queries. Default 'OR'.
- * Accepts 'OR', 'AND'.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * the `$default_column` parameter. Accepts 'post_date', 'post_date_gmt',
+ * 'post_modified','post_modified_gmt', 'comment_date', 'comment_date_gmt'.
+ * 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'.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @type array {
</span><span class="cx" style="display: block; padding: 0 10px"> * Optional. An array of first-order clause parameters, or another fully-formed date query.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @type string|array $before Optional. Date to retrieve posts before. Accepts strtotime()-compatible
- * string, or array of 'year', 'month', 'day' values. {
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @type string|array $before {
+ * Optional. Date to retrieve posts before. Accepts `strtotime()`-compatible string,
+ * or array of 'year', 'month', 'day' values.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @type string $year The four-digit year. Default empty. Accepts any four-digit year.
</span><span class="cx" style="display: block; padding: 0 10px"> * @type string $month Optional when passing array.The month of the year.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -94,43 +100,49 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @type string $day Optional when passing array.The day of the month.
</span><span class="cx" style="display: block; padding: 0 10px"> * Default (string:empty)|(array:1). Accepts numbers 1-31.
</span><span class="cx" style="display: block; padding: 0 10px"> * }
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @type string|array $after Optional. Date to retrieve posts after. Accepts strtotime()-compatible
- * string, or array of 'year', 'month', 'day' values. {
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @type string|array $after {
+ * Optional. Date to retrieve posts after. Accepts `strtotime()`-compatible string,
+ * or array of 'year', 'month', 'day' values.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @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:12). Accepts numbers 1-12.
- * @type string $day Optional when passing array.The day of the month.
- * Default (string:empty)|(array:last day of month). Accepts numbers 1-31.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @type string $year The four-digit year. Accepts any four-digit year. Default empty.
+ * @type string $month Optional when passing array. The month of the year. Accepts numbers 1-12.
+ * Default (string:empty)|(array:12).
+ * @type string $day Optional when passing array.The day of the month. Accepts numbers 1-31.
+ * Default (string:empty)|(array:last day of month).
</ins><span class="cx" style="display: block; padding: 0 10px"> * }
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @type string $column Optional. Used to add a clause comparing a column other than the column
- * specified in the top-level $column parameter. Default is the value
- * of top-level $column. Accepts 'post_date', 'post_date_gmt',
- * 'post_modified', 'post_modified_gmt', 'comment_date', 'comment_date_gmt'.
- * @type string $compare Optional. The comparison operator. Default '='.
- * Accepts '=', '!=', '>', '>=', '<', '<=', 'IN', 'NOT IN',
- * 'BETWEEN', 'NOT BETWEEN'.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @type string $column Optional. Used to add a clause comparing a column other than the
+ * column specified in the top-level `$column` parameter. Accepts
+ * 'post_date', 'post_date_gmt', 'post_modified', 'post_modified_gmt',
+ * 'comment_date', 'comment_date_gmt'. Default is the value of
+ * top-level `$column`.
+ * @type string $compare Optional. The comparison operator. Accepts '=', '!=', '>', '>=',
+ * '<', '<=', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. 'IN',
+ * 'NOT IN', 'BETWEEN', and 'NOT BETWEEN'. Comparisons support
+ * arrays in some time-related parameters. Default '='.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @type bool $inclusive Optional. Include results from dates specified in 'before' or
</span><span class="cx" style="display: block; padding: 0 10px"> * 'after'. Default false.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @type int $year Optional. The four-digit year number. Default empty. Accepts
- * any four-digit year.
- * @type int $month Optional. The two-digit month number. Default empty.
- * Accepts numbers 1-12.
- * @type int $week Optional. The week number of the year. Default empty.
- * Accepts numbers 0-53.
- * @type int $dayofyear Optional. The day number of the year. Default empty.
- * Accepts numbers 1-366.
- * @type int $day Optional. The day of the month. Default empty.
- * Accepts numbers 1-31.
- * @type int $dayofweek Optional. The day number of the week. Default empty.
- * Accepts numbers 1-7 (1 is Sunday).
- * @type int $dayofweek_iso Optional. The day number of the week (ISO). Accepts numbers 1-7
- * (1 is Monday). Default empty.
- * @type int $hour Optional. The hour of the day. Default empty. Accepts numbers 0-23.
- * @type int $minute Optional. The minute of the hour. Default empty. Accepts
- * numbers 0-60.
- * @type int $second Optional. The second of the minute. Default empty.
- * Accepts numbers 0-60.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @type int|array $year Optional. The four-digit year number. Accepts any four-digit year
+ * or an array of years if `$compare` supports it. Default empty.
+ * @type int|array $month Optional. The two-digit month number. Accepts numbers 1-12 or an
+ * array of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $week Optional. The week number of the year. Accepts numbers 0-53 or an
+ * array of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $dayofyear Optional. The day number of the year. Accepts numbers 1-366 or an
+ * array of valid numbers if `$compare` supports it.
+ * @type int|array $day Optional. The day of the month. Accepts numbers 1-31 or an array
+ * of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $dayofweek Optional. The day number of the week. Accepts numbers 1-7 (1 is
+ * Sunday) or an array of valid numbers if `$compare` supports it.
+ * Default empty.
+ * @type int|array $dayofweek_iso Optional. The day number of the week (ISO). Accepts numbers 1-7
+ * (1 is Monday) or an array of valid numbers if `$compare` supports it.
+ * Default empty.
+ * @type int|array $hour Optional. The hour of the day. Accepts numbers 0-23 or an array
+ * of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $minute Optional. The minute of the hour. Accepts numbers 0-60 or an array
+ * of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $second Optional. The second of the minute. Accepts numbers 0-60 or an
+ * array of valid numbers if `$compare` supports it. Default empty.
</ins><span class="cx" style="display: block; padding: 0 10px"> * }
</span><span class="cx" style="display: block; padding: 0 10px"> * }
</span><span class="cx" style="display: block; padding: 0 10px"> * }
</span></span></pre>
</div>
</div>
</body>
</html>