Doc #76378 [Opn->Csd]: strftime format "%p" is not always uppercase "AM/PM"

Edit report at https://bugs.php.net/bug.php?id=76378&edit=1

 ID:                 76378
 Updated by:         [email protected]
 Reported by:        webmaster at deltik dot org
 Summary:            strftime format "%p" is not always uppercase "AM/PM"
-Status:             Open
+Status:             Closed
 Type:               Documentation Problem
 Package:            Date/time related
 Operating System:   CloudLinux 7.5 and Ubuntu 18.04
 PHP Version:        Irrelevant
 Block user comment: N
 Private report:     N

 New Comment:

Automatic comment on behalf of derickr
Revision: https://github.com/php/doc-en/commit/9ff98b38276060be5c9e3fcd1aa6721f2f955213
Log: Fixed bug #76378: strftime format "%p" is not always uppercase "AM/PM"


Previous Comments:
------------------------------------------------------------------------
[2018-05-25 18:44:06] [email protected]

Also https://linux.die.net/man/3/strftime
> %P
> Like %p but in lowercase: "am" or "pm" or a corresponding string for the current locale. (GNU)
It's quite reasonable to assume from this that %p is uppercase.

The fact is that PHP can't guarantee much when it comes to strftime. Only document what systems tend to do. So if %p tends to be uppercase AM/PM then the docs should say that, and if that's not always the case then the docs should say that too.

------------------------------------------------------------------------
[2018-05-25 18:15:14] webmaster at deltik dot org

Regardless of the locale or operating system, the PHP documentation has the wrong description of the "%p" conversion specification because it assumes that the format will be uppercase.

------------
DOCUMENTATION WITHOUT UPPERCASE ASSUMPTION
------------

  https://msdn.microsoft.com/en-us/library/fe06s4ak.aspx
  > Current locale's A.M./P.M. indicator for 12-hour clock

  http://www.cplusplus.com/reference/ctime/strftime/
  > AM or PM designation

  https://www.freebsd.org/cgi/man.cgi?query=strftime
  > is replaced by national representation of either "ante meridiem" (a.m.)  or "post meridiem" (p.m.)  as appropriate.

  https://linux.die.net/man/3/strftime
  > Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM".

------------
DOCUMENTATION WITH UPPERCASE ASSUMPTION
------------

  https://secure.php.net/manual/en/function.strftime.php
  > UPPER-CASE 'AM' or 'PM' based on the given time

------------------------------------------------------------------------
[2018-05-25 17:54:42] [email protected]

PHP's strftime is a wrapper around the OS's strftime. I think it would be worth expanding the "Not all conversion specifiers..." paragraph (or adding a new one) to mention that while it's fairly well standardized, the exact behavior and output is system-dependent, "see your man page for strftime(3) or >>MSDN", something like that.

After some searching, it seems the docs for 'nix derivatives say "AM/PM" while BSD's is more broad.

So as far as I can tell, if you get "am/pm" in Ubuntu then that is contrary to its own strftime(3) docs which say it's either "AM" or "PM". Which means the locale is wrong, not PHP or the system.

------------------------------------------------------------------------
[2018-05-25 16:17:22] webmaster at deltik dot org

Description:
------------
When the LC_TIME locale is set to "en_GB.UTF-8", the "%p" conversion specification returns lowercase "am" or "pm" instead of the documented "AM" or "PM".

PHP documentation: https://secure.php.net/manual/en/function.strftime.php

The documentation for the "%p" conversion specification reads:

> UPPER-CASE 'AM' or 'PM' based on the given time

In `man 3 strftime`, the description reads:

> Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale.  Noon is treated as "PM" and midnight as "AM".

The "en_GB.UTF-8" locale always expresses "am" and "pm" as lowercase, which makes the PHP documentation inaccurate.

Sources:

- https://sourceware.org/bugzilla/show_bug.cgi?id=3768
- https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom

The documentation should be updated to explain that "%p" is "AM" or "PM" in the current locale, not necessarily uppercase, and that "%P" is the same as "%p" except lowercase.

---------------

This bug was discovered in a unit test of a PHP application:
https://github.com/e107inc/e107-test/pull/5#issuecomment-391903312

---------------

The "Expected result" below is what we should see if the PHP documentation were to be trusted.
The "Actual result" is correct according to the actual `strftime` function.

Test script:
---------------
<?php

echo setlocale(LC_TIME, "en_GB.UTF-8") . PHP_EOL . strftime("%I:%M %p", "1517834703") . PHP_EOL;
echo                                                                                    PHP_EOL;
echo setlocale(LC_TIME, "C")           . PHP_EOL . strftime("%I:%M %p", "1517834703") . PHP_EOL;

Expected result:
----------------
en_GB.UTF-8
12:45 PM

C
12:45 PM

Actual result:
--------------
en_GB.UTF-8
12:45 pm

C
12:45 PM


------------------------------------------------------------------------



--
Edit this bug report at https://bugs.php.net/bug.php?id=76378&edit=1