php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #74122 Incorrect and too restrictive description of the arguments of imap_list, etc.
Submitted: 2017-02-17 23:53 UTC Modified: 2017-04-17 05:56 UTC
Votes:1
Avg. Score:4.0 ± 0.0
Reproduced:0 of 1 (0.0%)
From: dominic_mayers at yahoo dot com Assigned:
Status: Open Package: IMAP related
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
Have you experienced this issue?
Rate the importance of this bug to you:

 [2017-02-17 23:53 UTC] dominic_mayers at yahoo dot com
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.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2017-02-18 15:39 UTC] cmb@php.net
-Package: Documentation problem +Package: IMAP related
 [2017-02-19 00:07 UTC] dominic_mayers at yahoo dot com
-Summary: Incorrect and too restrisctive description of the arguments of imap_list, etc. +Summary: Incorrect and too restrictive description of the arguments of imap_list, etc.
 [2017-02-19 00:07 UTC] dominic_mayers at yahoo dot com
Typo in description
 [2017-02-21 08:51 UTC] dominic_mayers at yahoo dot com
<?php
// This code demonstrates the features that are not well documented.
// The main point is that the selected mailbox in imap_open (reopen)
// and the specified mailbox in other imap functions are unrelated.  
// It has been tested with Gmail and with a Dovecot IMAP server. 
// The mailbox separator depends on the server. Gmail: "/"  Dovecot: "." 
// For Gmail, you need to turn on "Access for less secure apps".
 
  $server    = "{imap.gmail.com:993/imap/ssl/novalidate-cert}"; 
  $email     = "example@gmail.com"; 
  $password  = "password";
 
  // The code assumes that the folders Test/Sub1/Sub11, etc. exist. 
  $selected  = "{$server}Test/Sub1/Sub12";
  $conn      = imap_open($selected, $email , $password);

  // This returns the $specified mailbox and its sub mailboxes, 
  // even if the $specified mailbox is outside the $selected mailbox. 
  $specified =  "{$server}Test/Sub1"; 
  $boxes     = imap_list($conn, $specified , '*');
  print_r($boxes);
  
  // This appends the message in the $specified mailbox. 
  // It ignores the $selected mailbox. 
  imap_append($conn, $specified
                     , "From: me@example.com\r\n"
                     . "To: you@example.com\r\n"
                     . "Subject: test\r\n"
                     . "\r\n"
                     . "this is a test message, please ignore\r\n");

  // This changes the $selected mailbox
  $selected = "{$server}Test/Sub1"; 
  imap_reopen($conn, $selected); 

  // This moves a message from the $selected to the $specified mailbox
  // Note the format to specify the mailbox does not include the server. 
  imap_mail_move ($conn , "1" ,  "Test"); 
  imap_expunge($conn); 
  imap_close($conn);
  // If you executed this code with a real IMAP server, 
  // the message is now in the Test mailbox !
?>
 [2017-04-17 05:56 UTC] dominic_mayers at yahoo dot com
Just to add that the rfc 3501 also makes a difference between a selected mailbox and a mailbox that is simply specified in a command. For example, in accordance with the rfc 3501, the command APPEND is valid in the authenticated state - it does not require a selected mailbox. The mailbox argument in the APPEND command specifies a mailbox, but does not select a mailbox. Only the commands SELECT and EXAMINE can change the state from authenticated to selected.
 
PHP Copyright © 2001-2019 The PHP Group
All rights reserved.
Last updated: Wed Oct 16 07:01:27 2019 UTC