php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #74121 Confusion between mailbox stream and arbitrary mailboxes as folders.
Submitted: 2017-02-17 21:20 UTC Modified: 2017-02-18 15:40 UTC
From: dominic_mayers at yahoo dot com Assigned:
Status: Open Package: IMAP related
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
View Add Comment Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
You can add a comment by following this link or if you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: dominic_mayers at yahoo dot com
New email:
PHP Version: OS:

 

 [2017-02-17 21:20 UTC] dominic_mayers at yahoo dot com
Description:
------------
---
From manual page: http://www.php.net/function.imap-open
---
My understanding of Mail technologies, MTA, MTU, POP3, IMAP, etc. is that an email (say dominic@example.com) is associated with a single mailbox, which can be at any given time associated with a single folder, say INBOX or Drafts, but only INBOX in the case of a mail delivery agent (MDA). So, INBOX, etc. are folders, not mailboxes. I know that implementations of IMAP servers and the associated RFCs, refer to these folders as mailboxes. However, Gmail, Mozilla in the context of Thunderbird, Microsoft Windows in the context of Outlook, Wikipedia in the context of email clients, etc. use the term IMAP folders when they refer to INBOX, etc. It is unfortunate that the PHP IMAP client implementation followed the naming convention used in IMAP servers and associated RFCs. So, I feel a clarification for those who expect the more natural and largely spread convention is necessary.

However, there is a lot more in this documentation bug than only a naming convention. In what follows I use the PHP imap convention. 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. This is not well explained in the documentation. 

In fact, it seems to have it wrong. The documentation in imap_list() and perhaps elsewhere adds to the confusion.  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.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2017-02-17 22:27 UTC] dominic_mayers at yahoo dot com
-Summary: Confusion between selected mailbox and arbitrary mailboxes as folders. +Summary: Confusion between mailbox stream and arbitrary mailboxes as folders.
 [2017-02-17 22:27 UTC] dominic_mayers at yahoo dot com
I changed the summary. The confusion is between mailbox streams and mailboxes as folders. In imap_open() and imap_reopen(), we select a mailbox as a folder. However, in imap_list() and other imap functions, we provide a sub mailbox stream - we are not interested in its folder aspect, the details of its content - we cannot delete, etc, which can only be done in the selected mailbox (folder).
 [2017-02-17 23:55 UTC] dominic_mayers at yahoo dot com
I realize that there were two issues in this bug report : the naming convention needs to be explained and the description of the argument ref in imap_list is too restrictive. So, I created a separate bug report for this second issue.
 [2017-02-18 15:40 UTC] cmb@php.net
-Package: Documentation problem +Package: IMAP related
 
PHP Copyright © 2001-2019 The PHP Group
All rights reserved.
Last updated: Wed Aug 21 01:01:35 2019 UTC