Description:
------------
---
From manual page: http://www.php.net/function.imap-search
---

If you set $criteria argument for imap_search function using string such as:

'SINCE "Mon, 28 Dec 2015 02:55:04 +0000" UNDELETED'

it will reformat the string to something like:

'UNDELETED SINCE 28-Dec-2015'

This is mostly a good thing, except:

1. Nowhere in imap_search documentation does it reflect this auto-correction behavior,

2. Nowhere in imap_search documentation does it indicate the algorithm or mechanism that is applied to the datetime sub-string to derive a "pure datetime" value for correct formatting,

3. Throughout the documentation User Notes thread, there are several references to confusion regarding the "correct date formatting", including those that encourage the formatting used in the documentation examples ( such as "8 August 2008" ) versus those that encourage following the RFC-3501 spec ( which would be "08-Aug-2008" for that same example). So the fact that PHP is automatically handling date strings to format to RFC-3501 formatting is not well-known or being leveraged in a reliable, intentional manner.

4. Since there is no indication of what algorithm is used for parsing input date strings, it is not clear whether the following:

'SINCE "12-01-2015" UNDELETED'

would be handled as:

a. Invalid (un-parseable) date string
b. 12-Jan-2015
c. 01-Dec-2015

5. Also, PHP uses current timezone set (either via INI directive or date_default_timezone_set, etc) for formatting to RTC-3501, so that change to local system timezone means different resulting IMAP search criteria.

Test script:
---------------
date_default_timezone_set('UTC');

$conn   = imap_open('{localhost:143}INBOX', 'user@example.org', 'password', OP_READONLY);

$since = date('r');

$criteria = "SINCE \"{$since}\" UNDELETED";

echo $criteria . PHP_EOL;

$search   = imap_search($conn, $criteria, SE_UID);

print_r($search);

Expected result:
----------------
1. IMAP search criteria are sent with actual value of $criteria argument, like:

    UID SEARCH SINCE "Mon, 28 Dec 2015 02:55:04 +0000" UNDELETED

OR

2. IMAP search criteria gets reformatted as it does currently, but with consistent results (independent of timezone) so that:

date_default_timezone_set('UTC');

$since = date('r');

$criteria = "SINCE \"{$since}\" UNDELETED";

VS

date_default_timezone_set('America/Los Angeles');

$since = date('r');

$criteria = "SINCE \"{$since}\" UNDELETED";

both result in same search criteria sent to IMAP server, like:

'UNDELETED SINCE 28-Dec-2015'

instead of the criteria, when timezone is set to UTC, being:

'UNDELETED SINCE 28-Dec-2015'

versus when timezone is set to "America/Los Angeles", with result being:

'UNDELETED SINCE 27-Dec-2015'

-----

Note that some of this is actually more of a weakness of the IMAP specification (which indicates that SINCE should not include time or timezone but doesn't indicate what pure date should be relative to), as well as a probable issue with IMAP server misbehaving and using its own local timezone when it shouldn't be. However, the fact that PHP does this auto-correction AND the fact that there is potential for problems due to date-related searches, it should be more clear in PHP documentation what to expect based on value passed in to imap_search function compared to SEARCH command that is actually sent to PHP server.