Doc #74122 [NEW]: Incorrect and too restrisctive description of the arguments of imap_list, etc.

From: dominic_mayers at yahoo dot com Operating system: PHP version: Irrelevant Package: Documentation problem Bug Type: Documentation Problem Bug description:Incorrect and too restrisctive description of the arguments of imap_list, etc. Description: ------------ --- From manual page: http://www.php.net/function.imap-list --- An email or mailbox stream can be associated with a different selected mailbox at any given time. This is a fundamental concept in the understanding of an IMAP client. When we call imap_open, we do not open a mailbox (folder), but an entire mailbox stream with its associated hierarchy of mailboxes and we also select the current mailbox at the same time. So, imap_open() does two things: open a mailbox stream and select the current mailbox. We can change the selected mailbox with imap_reopen(). This is not well explained in the documentation. In fact, it seems to have it wrong. The function imap_list() takes two arguments (+ a third for a pattern) : the first is the mailbox stream and the second is a mailbox in the hierarchy, **which does not have to be the selected mailbox.** This makes sense because this function does not need the details of the selected mailbox, so it ignores it. There are many other imap functions that ignores the selected folder for the same reason. The documentation in imap_list() and perhaps in other similar functions is wrong and fails to convey this basic understanding because it says explicitly that the second argument should normally be the selected folder given in imap_open(). This misses the basic point. It's a fundamental misunderstanding. -- Edit bug report at https://bugs.php.net/bug.php?id=74122&edit=1 -- Try a snapshot (PHP 5.4): https://bugs.php.net/fix.php?id=74122&r=trysnapshot54 Try a snapshot (PHP 5.5): https://bugs.php.net/fix.php?id=74122&r=trysnapshot55 Try a snapshot (trunk): https://bugs.php.net/fix.php?id=74122&r=trysnapshottrunk Fixed in SVN: https://bugs.php.net/fix.php?id=74122&r=fixed Fixed in release: https://bugs.php.net/fix.php?id=74122&r=alreadyfixed Need backtrace: https://bugs.php.net/fix.php?id=74122&r=needtrace Need Reproduce Script: https://bugs.php.net/fix.php?id=74122&r=needscript Try newer version: https://bugs.php.net/fix.php?id=74122&r=oldversion Not developer issue: https://bugs.php.net/fix.php?id=74122&r=support Expected behavior: https://bugs.php.net/fix.php?id=74122&r=notwrong Not enough info: https://bugs.php.net/fix.php?id=74122&r=notenoughinfo Submitted twice: https://bugs.php.net/fix.php?id=74122&r=submittedtwice register_globals: https://bugs.php.net/fix.php?id=74122&r=globals PHP 4 support discontinued: https://bugs.php.net/fix.php?id=74122&r=php4 Daylight Savings: https://bugs.php.net/fix.php?id=74122&r=dst IIS Stability: https://bugs.php.net/fix.php?id=74122&r=isapi Install GNU Sed: https://bugs.php.net/fix.php?id=74122&r=gnused Floating point limitations: https://bugs.php.net/fix.php?id=74122&r=float No Zend Extensions: https://bugs.php.net/fix.php?id=74122&r=nozend MySQL Configuration Error: https://bugs.php.net/fix.php?id=74122&r=mysqlcfg