[PHP-DOC] IMAP Documentation and Functionality

[Nicolas]

Perhaps you could pass these comments on to the relevant people...   I've just finished writing the main part of a mail client for a website in PHP, using the IMAP functions to talk to SMTP and POP3 servers.   I've rarely had so much trouble understanding a language construct...  Firstly, the documentation left loads out, requiring extensive use of Google to track down people who had had the same problem and provided workarounds.   Secondly, the imap_compose_mail function provides output that is useless when used with other PHP functions such as MAIL, because mail() requires that I quote the message headers separately from the message body, so I have to migrate to a lower level of programming and open sendmail sockets and the like rather than using built-in functions that one would expect to find.  After all, if you've gone to the trouble of building a function to put MIME messages together, it's reasonable to expect you've got a function that mails the output!   Finally, the IMAP functions sometimes put \n\r at the end of header lines -- when these are received by outlook, the additional \r is interpreted as meaning that this is the end of the headers, and therefore the MIME header lines are treated as message body, requiring further editing of the imap_mail_compose output.   All this would have been fine if I hadn't had to find out the hard way, by spending hours trying to figure out what was going wrong - and could probably therefore be fixed with some updating of the documentation.  The most common comment I found on all the PHP message boards was that the example given in the PHP manual under imap_mail_compose() was flawed, didn't work and was incomplete.   I'm not trying to be negative, this only really stands out because its juxtaposed with the excellent quality of the rest of the documentation.   Nicolas.