Zend Framework

Actually it is implemented, but you have to use Zend_Mail_Storage_Writable_Maildir, which also extends Zend_Mail_Storage_Folder_Maildir and includes quota support. Any help getting that in the docs in a comprehensible way is appreciated.

Thanks for the feedback. The obvious question is why? Why have two classes? If that method is not implemented in that class, then why make a stub for it that throws an exception with a false message. At least the exception can point programmer in the right direction: "Use use Zend_Mail_Storage_Writable_Maildir". Do the other Zend_Mail_Storage classes have this writable vs. read-only duplication?

If the other Zend_Mail_Storage classes do not have a separate Writable class, then I propose Zend_Mail_Storage_Maildir conform and the two classes be merged. If that is the way all of Zend_Mail_Storage classes are written, then we need to fix the docs in regards to all the Zend_Mail_Storage classes (not just Zend_Mail_Storage_Maildir) and write useful messages for the exceptions that are thrown.

In order for the docs to be written well, it would be good to know why the situation is this way and why one needs to use Zend_Mail_Storage_Writable_Maildir as well as Zend_Mail_Storage_Maildir (or maybe Zend_Mail_Storage_Maildir is obsolete?). If someone could explain this, the resulting documentation might be clearer.

Thanks!

Actually removeMessage() should be moved to Zend_Mail_Storage_Writable_Interface. This means Zend_Mail_Storage_Mbox and Zend_Mail_Storage_Maildir wouldn't need to implement it and give a strange exception. Or course it's an API change so we need to leave them as deprecated until we are allowed to break stuff.

The reason for having this method in the default API (Zend_Mail_Storage_Abstract) is, because a long time ago I wrote a POP3 class, which was the starting point for everything else. POP3 has just one operation that modifies the storage: removing a message. Not moving it to the writable interface was an oversight.

Zend_Mail_Storage_Mbox is another mail storage class, which is read-only. As there is no real standard and the format has a couple of problems it's just not possible to support writing to a mbox file in a safe way. Maildir does have some documentation, that might be counted as "standard" and clean implementations shouldn't leave the maildir in a bad state (but not everything is atomic, especially in Maildir++) it's possible to support writing to maildirs (including using Zend_Mail_Storage_Maildir_Writable for incoming mails) there might be problems if other programs/scripts use the maildir at the same time. That's when you might want a read-only access.

Did I shed some light on the reasons?

Yes, that is quite clear now. Thanks for explaining that. I will see what I can do to get the documentation amended. So if it's moved to Zend_Mail_Storage_Writable_Interface, all the Zend_Mail_Storage classes will inherit this method?

The docs could say something like this:

Note:
Due to historical reasons, there is a removeMessage() method stub in Zend_Mail_Storage_Maildir (Zend_Mail_Storage_Mbox also?). However, it's use will throw an exception. If you want to remove and email from either Maildir or Mbox, you should use Zend_Mail_Storage_Writable_Maildir::removeMessage() and Zend_Mail_Storage_Writable_Mbox::removeMessage().

In the future this will be cleaned up... (actually maybe not mention anything about the future as it seems there is still some decisions to made about it's implementation)

I've added a comment on http://framework.zend.com/manual/en/zend.mail.read.html where it refers to removing emails. Hopefully that is enough for now and proper documentation changes can be made once the methods and classes are in order.