Doc #61171 [NEW]: Ambiguous 'timezone' parameter description causes hair-pulling

From: Operating system: PHP version: Irrelevant Package: Date/time related Bug Type: Documentation Problem Bug description:Ambiguous 'timezone' parameter description causes hair-pulling Description: ------------ --- From manual page: http://www.php.net/datetime.construct#refsect1datetime.construct-parameters --- The timezone parameter is described as "A DateTimeZone object representing the desired time zone". This is really ambiguous, since it depends on the user's motivation for creating the DateTime object. For instance, I wanted to display a UTC date string as a UK date string, so my "desired" timezone was "Europe/London". That's not how it works, but because it says "desired", that's how it sounds like it works. This sounds insignificant really, but I wasted an hour figuring out why it wasn't working (date problems are tough because dates are affected by absolutely everything in a system!), and I'm sure many other people have encountered the same problem. I suggest the timezone parameter should be described as "A DateTimeZone object representing the timezone of the time parameter". Thanks! Test script: --------------- // What someone would do who "desired" to convert a date from UTC to UK time... $dateTime = new DateTime('2012-05-01 23:00:00UTC', 'Europe/London'); echo $dateTime->format("Y-m-d H:i:s e"); // produces... // 2012-05-01 23:00:00 UTC // The actual way to do it... $dateTime = new DateTime('2012-05-01 23:00:00UTC'); $dateTime->setTimezone(new DateTimeZone('Europe/London')); echo $dateTime->format("Y-m-d H:i:s e"); // produces... // 2012-05-02 00:00:00 Europe/London -- Edit bug report at https://bugs.php.net/bug.php?id=61171&edit=1 -- Try a snapshot (PHP 5.4): https://bugs.php.net/fix.php?id=61171&r=trysnapshot54 Try a snapshot (PHP 5.3): https://bugs.php.net/fix.php?id=61171&r=trysnapshot53 Try a snapshot (trunk): https://bugs.php.net/fix.php?id=61171&r=trysnapshottrunk Fixed in SVN: https://bugs.php.net/fix.php?id=61171&r=fixed Fixed in SVN and need be documented: https://bugs.php.net/fix.php?id=61171&r=needdocs Fixed in release: https://bugs.php.net/fix.php?id=61171&r=alreadyfixed Need backtrace: https://bugs.php.net/fix.php?id=61171&r=needtrace Need Reproduce Script: https://bugs.php.net/fix.php?id=61171&r=needscript Try newer version: https://bugs.php.net/fix.php?id=61171&r=oldversion Not developer issue: https://bugs.php.net/fix.php?id=61171&r=support Expected behavior: https://bugs.php.net/fix.php?id=61171&r=notwrong Not enough info: https://bugs.php.net/fix.php?id=61171&r=notenoughinfo Submitted twice: https://bugs.php.net/fix.php?id=61171&r=submittedtwice register_globals: https://bugs.php.net/fix.php?id=61171&r=globals PHP 4 support discontinued: https://bugs.php.net/fix.php?id=61171&r=php4 Daylight Savings: https://bugs.php.net/fix.php?id=61171&r=dst IIS Stability: https://bugs.php.net/fix.php?id=61171&r=isapi Install GNU Sed: https://bugs.php.net/fix.php?id=61171&r=gnused Floating point limitations: https://bugs.php.net/fix.php?id=61171&r=float No Zend Extensions: https://bugs.php.net/fix.php?id=61171&r=nozend MySQL Configuration Error: https://bugs.php.net/fix.php?id=61171&r=mysqlcfg