incubator-zeta-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jero...@apache.org
Subject [zeta-commits] svn commit: r1154102 [1/2] - in /incubator/zetacomponents: trunk/Mail/docs/ trunk/MvcTools/docs/ website/htdocs/documentation/trunk/ website/htdocs/documentation/trunk/Mail/ website/htdocs/documentation/trunk/MvcTools/
Date Fri, 05 Aug 2011 07:22:46 GMT
Author: jeromer
Date: Fri Aug  5 07:22:45 2011
New Revision: 1154102

URL: http://svn.apache.org/viewvc?rev=1154102&view=rev
Log:
- Fixed #ZETACOMP-49: security notes are missing about MvcTools and Mail

Modified:
    incubator/zetacomponents/trunk/Mail/docs/tutorial.txt
    incubator/zetacomponents/trunk/MvcTools/docs/tutorial.txt
    incubator/zetacomponents/website/htdocs/documentation/trunk/Mail.html
    incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.html
    incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.txt
    incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools.html
    incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.html
    incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.txt

Modified: incubator/zetacomponents/trunk/Mail/docs/tutorial.txt
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/trunk/Mail/docs/tutorial.txt?rev=1154102&r1=1154101&r2=1154102&view=diff
==============================================================================
--- incubator/zetacomponents/trunk/Mail/docs/tutorial.txt (original)
+++ incubator/zetacomponents/trunk/Mail/docs/tutorial.txt Fri Aug  5 07:22:45 2011
@@ -686,6 +686,22 @@ available on the next request.
 .. _iconv: http://php.net/manual/en/function.iconv.php
 
 
+Security
+========
+
+Excluding the User-Agent header
+-------------------------------
+
+By defaul the Mail component will add the "User-Agent" header containing the
+string "Apache Zeta Components". This can be considered a security issue. If
+you do not want to get this header sent along with the email you can use the
+following code: ::
+
+    $mail = new ezcMailComposer();
+    // [...]
+    $mail->appendExcludeHeaders(array('User-Agent'));
+
+
 
 ..
    Local Variables:

Modified: incubator/zetacomponents/trunk/MvcTools/docs/tutorial.txt
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/trunk/MvcTools/docs/tutorial.txt?rev=1154102&r1=1154101&r2=1154102&view=diff
==============================================================================
--- incubator/zetacomponents/trunk/MvcTools/docs/tutorial.txt (original)
+++ incubator/zetacomponents/trunk/MvcTools/docs/tutorial.txt Fri Aug  5 07:22:45 2011
@@ -592,6 +592,18 @@ The full directory listing is now::
     │   └── index.php
     └── config.php
 
+Security
+========
+
+Overriding the X-Powered-By header
+----------------------------------
+
+By default, the MvcTools component will add an `X-Powered-By` HTTP header
+containing the string "Apache Zeta Components MvcTools" or "eZ Components
+MvcTools". This can be considered a security issue. If you want to modify
+this header you can add the following code in your response filter: ::
+
+    $response->generator = "Whatever you want here";
 
 
 ..

Modified: incubator/zetacomponents/website/htdocs/documentation/trunk/Mail.html
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/documentation/trunk/Mail.html?rev=1154102&r1=1154101&r2=1154102&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/documentation/trunk/Mail.html (original)
+++ incubator/zetacomponents/website/htdocs/documentation/trunk/Mail.html Fri Aug  5 07:22:45 2011
@@ -12,13 +12,13 @@
 	<meta name="keywords" content="PHP, apache, components, framework, quality" />
 	<meta name="author" content="jerome" />
 	<meta name="language" content="en" />
-	<meta name="date" content="Sun, 10 Jul 2011 11:10:39 +0200" />
+	<meta name="date" content="Fri, 05 Aug 2011 09:14:15 +0200" />
 	<meta name="robots" content="all" />
 
 	<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
 	<meta name="DC.title" content="Mail" />
 	<meta name="DC.creator" content="jerome" />
-	<meta name="DC.date" content="Sun, 10 Jul 2011 11:10:39 +0200" />
+	<meta name="DC.date" content="Fri, 05 Aug 2011 09:14:15 +0200" />
 	<meta name="DC.rights" content="Copyright" />
 
 	<link rel="meta" href="/zetacomponents/documentation/trunk/Mail/tutorial.rdf" />
@@ -86,7 +86,7 @@
 
 </ul>
 
-		<h2>eZ Components - Mail</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p></li><li><p><a href="#class-overview">Class overview</a></p></li><li><p><a href="#usage">Usage</a></p><ul><li><p><a href="#transport-protocols">Transport protocols</a></p></li><li><p><a href="#mail-parsers">Mail parsers</a></p></li><li><p><a href="#mail-parts">Mail parts</a></p></li><li><p><a href="#mail-tools">Mail tools</a></p></li></ul></li><li><p><a href="#building-and-sending-mail">Building and sending mail</a></p><ul><li><p><a href="#sending-a-mail-with-the-composer">Sending a mail with the composer</a></p></li><li><p><a href="#sending-a-mail-with-html-inline-images-and-attachments">Sending a mail with HTML, inline images and attachments</a></p></li><li><p><a href="#securing-html-mails-which-include-file-in-image-tags">Securing HTML mails which include file:// in image tags</a></p></li><li><p><a href="#building-a-mail-from-scratch">Building a
  mail from scratch</a></p></li><li><p><a href="#building-mime-structures-that-work">Building MIME structures that work</a></p></li><li><p><a href="#sending-a-mail-using-smtp">Sending a mail using SMTP</a></p></li><li><p><a href="#using-stronger-authentication-methods-with-the-smtp-transports">Using stronger authentication methods with the SMTP transports</a></p></li><li><p><a href="#avoid-bcc-headers-appearing-in-the-sent-mails">Avoid Bcc headers appearing in the sent mails</a></p></li><li><p><a href="#character-encoding">Character encoding</a></p></li><li><p><a href="#extending-the-mail-component">Extending the Mail component</a></p></li><li><p><a href="#using-the-ezcmailtools-class">Using the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> class</a></p></li></ul></li><li><p><a href="#mail-retrieval-and-parsing">Mail retrieval and parsing</a></p><ul><li><p><a href="#retrieving-mail-using-pop3">Retrieving mail using POP3</a></p></
 li><li><p><a href="#retrieving-mail-using-imap">Retrieving mail using IMAP</a></p></li><li><p><a href="#additional-usage-of-the-imap-transport">Additional usage of the IMAP transport</a></p></li><li><p><a href="#refering-messages-by-their-unique-ids-in-imap">Refering messages by their unique IDs in IMAP</a></p></li><li><p><a href="#working-with-transport-options">Working with transport options</a></p></li><li><p><a href="#using-ssl-with-pop3-and-imap">Using SSL with POP3 and IMAP</a></p></li><li><p><a href="#retrieving-mail-from-mbox-files">Retrieving mail from mbox files</a></p></li><li><p><a href="#parsing-a-message-set">Parsing a message set</a></p></li><li><p><a href="#displaying-html-mail-with-inline-images">Displaying HTML mail with inline images</a></p></li><li><p><a href="#using-a-custom-mail-class">Using a custom mail class</a></p></li><li><p><a href="#using-a-custom-file-class">Using a custom file class</a></p></li></ul></li><li><p><a href="#troubleshooting">Troubl
 eshooting</a></p><ul><li><p><a href="#mta-qmail">MTA: Qmail</a></p></li><li><p><a href="#mta-sendmail-relaying-denied">MTA: Sendmail relaying denied</a></p></li><li><p><a href="#imap-authentication-failed">IMAP: Authentication failed</a></p></li><li><p><a href="#imap-could-not-read-from-the-stream">IMAP: Could not read from the stream</a></p></li><li><p><a href="#parsing-iconv-notices">Parsing: iconv() notices</a></p></li><li><p><a href="#parsing-missing-characters">Parsing: missing characters</a></p></li><li><p><a href="#parsing-broken-headers">Parsing: broken headers</a></p></li><li><p><a href="#parsing-multiple-value-headers">Parsing: multiple-value headers</a></p></li><li><p><a href="#parsing-text-attachments-as-file-parts">Parsing: text attachments as file parts</a></p></li><li><p><a href="#parsing-attachment-file-names">Parsing: attachment file names</a></p></li></ul></li></ul></div><a name="introduction"></a><a name="id2"></a><h3>Introduction</h3><p>The Mail component
  provides functionality to send, retrieve and parse mail messages. If you require an easy way to send a mail, use the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> class, which allows you to send HTML mails with images, attachments and an optional text part. If you require more advanced mail messages, you can build the complete message yourself using the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailPart.html'>ezcMailPart</a> derived classes. You can retrieve mail messages from different sources using the supported transports.</p><a name="class-overview"></a><a name="id3"></a><h3>Class overview</h3><p>This section gives you an overview of the main classes in the Mail component.</p><dl><dt>ezcMailComposer</dt><dd>This is a convenience class that allows you to send plain text or HTML messages with attachments, without having to construct the parts of the message yourself. Most users will use this class.</dd
 ><dt>ezcMail</dt><dd>If <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> does not have the functionality you require, you can use the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> class to build MIME-structured mail from scratch. This requires basic knowledge about how a mail is structured.</dd><dt>ezcMailAddress</dt><dd>This small class represents a mail address with an optional name. It is used by both <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> and <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> to set recipient addresses.</dd><dt>ezcMailParser</dt><dd>This class parses mail messages from text into <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> structures. You can use it together with the mail retrieval transport classes.</dd><dt>ezcMailSmtpTransport</dt><dd>Send
 s mails using an SMTP server. After sending a mail, the connection can be kept alive so that the next mail sent uses the same connection, speeding up the process.</dd><dt>ezcMailMtaTransport</dt><dd>Sends mails using the PHP mail() function.</dd><dt>ezcMailPop3Transport</dt><dd>Connects to a POP3 server and allows the fetching and deleting of mails.</dd><dt>ezcMailImapTransport</dt><dd>Connects to an IMAP server and allows operations on mails in a mailbox (fetch, delete) and operations on mailboxes (create, delete, rename, append).</dd></dl><a name="usage"></a><a name="id4"></a><h3>Usage</h3><a name="transport-protocols"></a><a name="id5"></a><h4>Transport protocols</h4><p>The Mail component provides transport protocols for both sending and retrieving mail.</p><p>For sending mail, the following protocols are supported:</p><ul><li><p>SMTP (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailSmtpTransport.html'>ezcMailSmtpTransport</a>) - uses an SMTP server to sen
 d mail. Supports plain and TLS/SSL/SSLv2/SSLv3 connections.</p></li><li><p>MTA (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailMtaTransport.html'>ezcMailMtaTransport</a>) - wraps around the PHP mail() function.</p></li></ul><p>For mail retrieval we currently support the following protocols:</p><ul><li><p>POP3 (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailPop3Transport.html'>ezcMailPop3Transport</a>) - an old protocol but still used. SSL is supported.</p></li><li><p>IMAP (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailImapTransport.html'>ezcMailImapTransport</a>) - handles multiple mailboxes. SSL is supported.</p></li><li><p>MBOX (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailMboxTransport.html'>ezcMailMboxTransport</a>) - handles Unix mailbox file formats.</p></li></ul><p>Mail retrieval from other sources include:</p><ul><li><p>File (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailFileSet.
 html'>ezcMailFileSet</a>) - handles mails stored in files.</p></li><li><p>Variable (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailVariableSet.html'>ezcMailVariableSet</a>) - handles mails stored in memory.</p></li></ul><a name="mail-parsers"></a><a name="id6"></a><h4>Mail parsers</h4><p>After using a mail retrieval transport to fetch a set of mails, a mail parser can be used to go through the set and extract the needed information like subject, sender, date and attachments from each mail in the set. The <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailParser.html'>ezcMailParser</a> class is used for this purpose.</p><a name="mail-parts"></a><a name="id7"></a><h4>Mail parts</h4><p>The <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> component supports a wide variety of mail parts that can be used when sending or retrieving mails:</p><ul><li><p>ezcMailFile - mail attachment from an existing file</p></li><li><p>
 ezcMailStreamFile - mail attachment from an open stream</p></li><li><p>ezcMailVirtualFile - mail attachment from a string in memory</p></li><li><p>ezcMailMultipartAlternative - used to bundle a group of mail parts where only one should be shown</p></li><li><p>ezcMailMultipartDigest - used to bundle a list of mail objects</p></li><li><p>ezcMailMultipartMixed - used to bundle an ordered list of mail parts</p></li><li><p>ezcMailMultipartRelated - intended for mail parts consisting of several inter-related body parts</p></li><li><p>ezcMailMultipartReport - used for sending delivery status notifications</p></li><li><p>ezcMailDeliveryStatus - used for sending delivery status notifications</p></li><li><p>ezcMailRfc822Digest - used to insert another mail into a mail</p></li><li><p>ezcMailText - used for plain text</p></li></ul><a name="mail-tools"></a><a name="id8"></a><h4>Mail tools</h4><p>In the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailToo
 ls</a> class, you will find various useful static methods that can be used in your applications:</p><ul><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#lineBreak'>ezcMailTools::lineBreak</a>() - returns one end-of-line character (default \r\n). Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#setLineBreak'>ezcMailTools::setLineBreak</a>() to change the default</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#composeEmailAddress'>ezcMailTools::composeEmailAddress</a>() - returns the RFC822 representation of a mail address as a string. Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#composeEmailAddresses'>ezcMailTools::composeEmailAddresses</a>() for an array of mail address objects</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#parseEmailAddress'>ezcMailTools::parseEmailAddress</a>() - returns an <a 
 href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailAddress.html'>ezcMailAddress</a> object from a string mail address. Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#parseEmailAddresses'>ezcMailTools::parseEmailAddresses</a>() for a string of mail addresses</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#generateMessageId'>ezcMailTools::generateMessageId</a>() - returns a unique message ID to be used for a mail message</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#generateContentId'>ezcMailTools::generateContentId</a>() - returns a unique ID to be used for Content-ID headers</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#mimeDecode'>ezcMailTools::mimeDecode</a>() - decodes MIME-encoded fields and tries to recover from errors</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTool
 s.html#replyToMail'>ezcMailTools::replyToMail</a>() - returns a new <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> object that is a reply to the specified <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> object</p></li></ul><p>See the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> example below for information on how to use these methods.</p><a name="building-and-sending-mail"></a><a name="id9"></a><h3>Building and sending mail</h3><p>eZ components provides two ways to create mail. The simplest is to use the composer class <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a>. Using the composer you can send plain text messages, HTML messages with images and messages with attachments. If you require more advanced messages you can also customize them entirely by building it from the scratch using the various part type
 s in <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a>. The part types are structured the same way as the underlying mail MIME types.</p><a name="sending-a-mail-with-the-composer"></a><a name="id10"></a><h4>Sending a mail with the composer</h4><p>Sending a mail using the composer is very straightforward. This small example displays how to send a normal text message.</p><ol class="code">
+		<h2>eZ Components - Mail</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p></li><li><p><a href="#class-overview">Class overview</a></p></li><li><p><a href="#usage">Usage</a></p><ul><li><p><a href="#transport-protocols">Transport protocols</a></p></li><li><p><a href="#mail-parsers">Mail parsers</a></p></li><li><p><a href="#mail-parts">Mail parts</a></p></li><li><p><a href="#mail-tools">Mail tools</a></p></li></ul></li><li><p><a href="#building-and-sending-mail">Building and sending mail</a></p><ul><li><p><a href="#sending-a-mail-with-the-composer">Sending a mail with the composer</a></p></li><li><p><a href="#sending-a-mail-with-html-inline-images-and-attachments">Sending a mail with HTML, inline images and attachments</a></p></li><li><p><a href="#securing-html-mails-which-include-file-in-image-tags">Securing HTML mails which include file:// in image tags</a></p></li><li><p><a href="#building-a-mail-from-scratch">Building a
  mail from scratch</a></p></li><li><p><a href="#building-mime-structures-that-work">Building MIME structures that work</a></p></li><li><p><a href="#sending-a-mail-using-smtp">Sending a mail using SMTP</a></p></li><li><p><a href="#using-stronger-authentication-methods-with-the-smtp-transports">Using stronger authentication methods with the SMTP transports</a></p></li><li><p><a href="#avoid-bcc-headers-appearing-in-the-sent-mails">Avoid Bcc headers appearing in the sent mails</a></p></li><li><p><a href="#character-encoding">Character encoding</a></p></li><li><p><a href="#extending-the-mail-component">Extending the Mail component</a></p></li><li><p><a href="#using-the-ezcmailtools-class">Using the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> class</a></p></li></ul></li><li><p><a href="#mail-retrieval-and-parsing">Mail retrieval and parsing</a></p><ul><li><p><a href="#retrieving-mail-using-pop3">Retrieving mail using POP3</a></p></
 li><li><p><a href="#retrieving-mail-using-imap">Retrieving mail using IMAP</a></p></li><li><p><a href="#additional-usage-of-the-imap-transport">Additional usage of the IMAP transport</a></p></li><li><p><a href="#refering-messages-by-their-unique-ids-in-imap">Refering messages by their unique IDs in IMAP</a></p></li><li><p><a href="#working-with-transport-options">Working with transport options</a></p></li><li><p><a href="#using-ssl-with-pop3-and-imap">Using SSL with POP3 and IMAP</a></p></li><li><p><a href="#retrieving-mail-from-mbox-files">Retrieving mail from mbox files</a></p></li><li><p><a href="#parsing-a-message-set">Parsing a message set</a></p></li><li><p><a href="#displaying-html-mail-with-inline-images">Displaying HTML mail with inline images</a></p></li><li><p><a href="#using-a-custom-mail-class">Using a custom mail class</a></p></li><li><p><a href="#using-a-custom-file-class">Using a custom file class</a></p></li></ul></li><li><p><a href="#troubleshooting">Troubl
 eshooting</a></p><ul><li><p><a href="#mta-qmail">MTA: Qmail</a></p></li><li><p><a href="#mta-sendmail-relaying-denied">MTA: Sendmail relaying denied</a></p></li><li><p><a href="#imap-authentication-failed">IMAP: Authentication failed</a></p></li><li><p><a href="#imap-could-not-read-from-the-stream">IMAP: Could not read from the stream</a></p></li><li><p><a href="#parsing-iconv-notices">Parsing: iconv() notices</a></p></li><li><p><a href="#parsing-missing-characters">Parsing: missing characters</a></p></li><li><p><a href="#parsing-broken-headers">Parsing: broken headers</a></p></li><li><p><a href="#parsing-multiple-value-headers">Parsing: multiple-value headers</a></p></li><li><p><a href="#parsing-text-attachments-as-file-parts">Parsing: text attachments as file parts</a></p></li><li><p><a href="#parsing-attachment-file-names">Parsing: attachment file names</a></p></li></ul></li><li><p><a href="#security">Security</a></p><ul><li><p><a href="#excluding-the-user-agent-header">E
 xcluding the User-Agent header</a></p></li></ul></li></ul></div><a name="introduction"></a><a name="id2"></a><h3>Introduction</h3><p>The Mail component provides functionality to send, retrieve and parse mail messages. If you require an easy way to send a mail, use the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> class, which allows you to send HTML mails with images, attachments and an optional text part. If you require more advanced mail messages, you can build the complete message yourself using the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailPart.html'>ezcMailPart</a> derived classes. You can retrieve mail messages from different sources using the supported transports.</p><a name="class-overview"></a><a name="id3"></a><h3>Class overview</h3><p>This section gives you an overview of the main classes in the Mail component.</p><dl><dt>ezcMailComposer</dt><dd>This is a convenience class that allows you t
 o send plain text or HTML messages with attachments, without having to construct the parts of the message yourself. Most users will use this class.</dd><dt>ezcMail</dt><dd>If <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> does not have the functionality you require, you can use the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> class to build MIME-structured mail from scratch. This requires basic knowledge about how a mail is structured.</dd><dt>ezcMailAddress</dt><dd>This small class represents a mail address with an optional name. It is used by both <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> and <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> to set recipient addresses.</dd><dt>ezcMailParser</dt><dd>This class parses mail messages from text into <a href='/zetacomponents/documentation/trunk/Mail/ph
 pdoc/ezcMail.html'>ezcMail</a> structures. You can use it together with the mail retrieval transport classes.</dd><dt>ezcMailSmtpTransport</dt><dd>Sends mails using an SMTP server. After sending a mail, the connection can be kept alive so that the next mail sent uses the same connection, speeding up the process.</dd><dt>ezcMailMtaTransport</dt><dd>Sends mails using the PHP mail() function.</dd><dt>ezcMailPop3Transport</dt><dd>Connects to a POP3 server and allows the fetching and deleting of mails.</dd><dt>ezcMailImapTransport</dt><dd>Connects to an IMAP server and allows operations on mails in a mailbox (fetch, delete) and operations on mailboxes (create, delete, rename, append).</dd></dl><a name="usage"></a><a name="id4"></a><h3>Usage</h3><a name="transport-protocols"></a><a name="id5"></a><h4>Transport protocols</h4><p>The Mail component provides transport protocols for both sending and retrieving mail.</p><p>For sending mail, the following protocols are supported:</p><ul>
 <li><p>SMTP (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailSmtpTransport.html'>ezcMailSmtpTransport</a>) - uses an SMTP server to send mail. Supports plain and TLS/SSL/SSLv2/SSLv3 connections.</p></li><li><p>MTA (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailMtaTransport.html'>ezcMailMtaTransport</a>) - wraps around the PHP mail() function.</p></li></ul><p>For mail retrieval we currently support the following protocols:</p><ul><li><p>POP3 (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailPop3Transport.html'>ezcMailPop3Transport</a>) - an old protocol but still used. SSL is supported.</p></li><li><p>IMAP (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailImapTransport.html'>ezcMailImapTransport</a>) - handles multiple mailboxes. SSL is supported.</p></li><li><p>MBOX (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailMboxTransport.html'>ezcMailMboxTransport</a>) - handles Unix mailbox file formats.<
 /p></li></ul><p>Mail retrieval from other sources include:</p><ul><li><p>File (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailFileSet.html'>ezcMailFileSet</a>) - handles mails stored in files.</p></li><li><p>Variable (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailVariableSet.html'>ezcMailVariableSet</a>) - handles mails stored in memory.</p></li></ul><a name="mail-parsers"></a><a name="id6"></a><h4>Mail parsers</h4><p>After using a mail retrieval transport to fetch a set of mails, a mail parser can be used to go through the set and extract the needed information like subject, sender, date and attachments from each mail in the set. The <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailParser.html'>ezcMailParser</a> class is used for this purpose.</p><a name="mail-parts"></a><a name="id7"></a><h4>Mail parts</h4><p>The <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> component supports a wide var
 iety of mail parts that can be used when sending or retrieving mails:</p><ul><li><p>ezcMailFile - mail attachment from an existing file</p></li><li><p>ezcMailStreamFile - mail attachment from an open stream</p></li><li><p>ezcMailVirtualFile - mail attachment from a string in memory</p></li><li><p>ezcMailMultipartAlternative - used to bundle a group of mail parts where only one should be shown</p></li><li><p>ezcMailMultipartDigest - used to bundle a list of mail objects</p></li><li><p>ezcMailMultipartMixed - used to bundle an ordered list of mail parts</p></li><li><p>ezcMailMultipartRelated - intended for mail parts consisting of several inter-related body parts</p></li><li><p>ezcMailMultipartReport - used for sending delivery status notifications</p></li><li><p>ezcMailDeliveryStatus - used for sending delivery status notifications</p></li><li><p>ezcMailRfc822Digest - used to insert another mail into a mail</p></li><li><p>ezcMailText - used for plain text</p></li></ul><a name
 ="mail-tools"></a><a name="id8"></a><h4>Mail tools</h4><p>In the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> class, you will find various useful static methods that can be used in your applications:</p><ul><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#lineBreak'>ezcMailTools::lineBreak</a>() - returns one end-of-line character (default \r\n). Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#setLineBreak'>ezcMailTools::setLineBreak</a>() to change the default</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#composeEmailAddress'>ezcMailTools::composeEmailAddress</a>() - returns the RFC822 representation of a mail address as a string. Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#composeEmailAddresses'>ezcMailTools::composeEmailAddresses</a>() for an array of mail address objects</p></li><li>
 <p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#parseEmailAddress'>ezcMailTools::parseEmailAddress</a>() - returns an <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailAddress.html'>ezcMailAddress</a> object from a string mail address. Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#parseEmailAddresses'>ezcMailTools::parseEmailAddresses</a>() for a string of mail addresses</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#generateMessageId'>ezcMailTools::generateMessageId</a>() - returns a unique message ID to be used for a mail message</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#generateContentId'>ezcMailTools::generateContentId</a>() - returns a unique ID to be used for Content-ID headers</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#mimeDecode'>ezcMailTools::mimeDecode</
 a>() - decodes MIME-encoded fields and tries to recover from errors</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#replyToMail'>ezcMailTools::replyToMail</a>() - returns a new <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> object that is a reply to the specified <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> object</p></li></ul><p>See the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> example below for information on how to use these methods.</p><a name="building-and-sending-mail"></a><a name="id9"></a><h3>Building and sending mail</h3><p>eZ components provides two ways to create mail. The simplest is to use the composer class <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a>. Using the composer you can send plain text messages, HTML messages with images and messages w
 ith attachments. If you require more advanced messages you can also customize them entirely by building it from the scratch using the various part types in <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a>. The part types are structured the same way as the underlying mail MIME types.</p><a name="sending-a-mail-with-the-composer"></a><a name="id10"></a><h4>Sending a mail with the composer</h4><p>Sending a mail using the composer is very straightforward. This small example displays how to send a normal text message.</p><ol class="code">
 <li><span style="color: #000000">&lt;?php</span></li>
 <li><span style="color: #0000FF">require_once&nbsp;</span><span style="color: #335533">'tutorial_autoload.php'</span><span style="color: #0000FF">;</span></li>
 <li></li>
@@ -817,7 +817,9 @@ $parser-&gt;parseMail( $set );</code><a 
     "from localhost (localhost) by www.example.com..."
      );</code><p>instead of only the first value as a string if the second parameter to getHeader() was not specified.</p><a name="parsing-text-attachments-as-file-parts"></a><a name="id42"></a><h4>Parsing: text attachments as file parts</h4><p>By default, the mail parser creates <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTextPart.html'>ezcMailTextPart</a> objects for text attachments found in the mail.</p><p>To create <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailFile.html'>ezcMailFile</a> objects instead (for example on servers where internal memory is limited), set this option to the mail parser before parsing:</p><code class="block">$parser = new <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailParser.html'>ezcMailParser</a>();
 $parser-&gt;options-&gt;parseTextAttachmentsAsFiles = true;
-// call $parser-&gt;parseMail( $set );</code><a name="parsing-attachment-file-names"></a><a name="id43"></a><h4>Parsing: attachment file names</h4><p>When parsing a mail with attachments you can use a code similar to the one in section . The mail part that contains the attachment ($part) has the <em>fileName</em> property which contains the raw file name, <em>contentDisposition-&gt;displayFileName</em> which contain the MIME-decoded file name. Use the <em>contentDisposition-&gt;displayFileName</em> value to copy the temporary files saved during parsing which contain the attachments, and which will not be available on the next request.</p><!--Local Variables:
+// call $parser-&gt;parseMail( $set );</code><a name="parsing-attachment-file-names"></a><a name="id43"></a><h4>Parsing: attachment file names</h4><p>When parsing a mail with attachments you can use a code similar to the one in section . The mail part that contains the attachment ($part) has the <em>fileName</em> property which contains the raw file name, <em>contentDisposition-&gt;displayFileName</em> which contain the MIME-decoded file name. Use the <em>contentDisposition-&gt;displayFileName</em> value to copy the temporary files saved during parsing which contain the attachments, and which will not be available on the next request.</p><a name="security"></a><a name="id44"></a><h3>Security</h3><a name="excluding-the-user-agent-header"></a><a name="id45"></a><h4>Excluding the User-Agent header</h4><p>By defaul the Mail component will add the "User-Agent" header containing the string "Apache Zeta Components". This can be considered a security issue. If you do not want to get
  this header sent along with the email you can use the following code:</p><code class="block">$mail = new <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a>();
+// [...]
+$mail-&gt;appendExcludeHeaders(array('User-Agent'));</code><!--Local Variables:
 mode: rst
 fill-column: 79
 End:

Modified: incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.html
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.html?rev=1154102&r1=1154101&r2=1154102&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.html (original)
+++ incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.html Fri Aug  5 07:22:45 2011
@@ -12,13 +12,13 @@
 	<meta name="keywords" content="PHP, apache, components, framework, quality" />
 	<meta name="author" content="jerome" />
 	<meta name="language" content="en" />
-	<meta name="date" content="Sun, 10 Jul 2011 11:10:39 +0200" />
+	<meta name="date" content="Fri, 05 Aug 2011 09:14:15 +0200" />
 	<meta name="robots" content="all" />
 
 	<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
 	<meta name="DC.title" content="Tutorial" />
 	<meta name="DC.creator" content="jerome" />
-	<meta name="DC.date" content="Sun, 10 Jul 2011 11:10:39 +0200" />
+	<meta name="DC.date" content="Fri, 05 Aug 2011 09:14:15 +0200" />
 	<meta name="DC.rights" content="Copyright" />
 
 	<link rel="meta" href="/zetacomponents/documentation/trunk/Mail/tutorial.rdf" />
@@ -86,7 +86,7 @@
 
 </ul>
 
-		<h2>eZ Components - Mail</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p></li><li><p><a href="#class-overview">Class overview</a></p></li><li><p><a href="#usage">Usage</a></p><ul><li><p><a href="#transport-protocols">Transport protocols</a></p></li><li><p><a href="#mail-parsers">Mail parsers</a></p></li><li><p><a href="#mail-parts">Mail parts</a></p></li><li><p><a href="#mail-tools">Mail tools</a></p></li></ul></li><li><p><a href="#building-and-sending-mail">Building and sending mail</a></p><ul><li><p><a href="#sending-a-mail-with-the-composer">Sending a mail with the composer</a></p></li><li><p><a href="#sending-a-mail-with-html-inline-images-and-attachments">Sending a mail with HTML, inline images and attachments</a></p></li><li><p><a href="#securing-html-mails-which-include-file-in-image-tags">Securing HTML mails which include file:// in image tags</a></p></li><li><p><a href="#building-a-mail-from-scratch">Building a
  mail from scratch</a></p></li><li><p><a href="#building-mime-structures-that-work">Building MIME structures that work</a></p></li><li><p><a href="#sending-a-mail-using-smtp">Sending a mail using SMTP</a></p></li><li><p><a href="#using-stronger-authentication-methods-with-the-smtp-transports">Using stronger authentication methods with the SMTP transports</a></p></li><li><p><a href="#avoid-bcc-headers-appearing-in-the-sent-mails">Avoid Bcc headers appearing in the sent mails</a></p></li><li><p><a href="#character-encoding">Character encoding</a></p></li><li><p><a href="#extending-the-mail-component">Extending the Mail component</a></p></li><li><p><a href="#using-the-ezcmailtools-class">Using the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> class</a></p></li></ul></li><li><p><a href="#mail-retrieval-and-parsing">Mail retrieval and parsing</a></p><ul><li><p><a href="#retrieving-mail-using-pop3">Retrieving mail using POP3</a></p></
 li><li><p><a href="#retrieving-mail-using-imap">Retrieving mail using IMAP</a></p></li><li><p><a href="#additional-usage-of-the-imap-transport">Additional usage of the IMAP transport</a></p></li><li><p><a href="#refering-messages-by-their-unique-ids-in-imap">Refering messages by their unique IDs in IMAP</a></p></li><li><p><a href="#working-with-transport-options">Working with transport options</a></p></li><li><p><a href="#using-ssl-with-pop3-and-imap">Using SSL with POP3 and IMAP</a></p></li><li><p><a href="#retrieving-mail-from-mbox-files">Retrieving mail from mbox files</a></p></li><li><p><a href="#parsing-a-message-set">Parsing a message set</a></p></li><li><p><a href="#displaying-html-mail-with-inline-images">Displaying HTML mail with inline images</a></p></li><li><p><a href="#using-a-custom-mail-class">Using a custom mail class</a></p></li><li><p><a href="#using-a-custom-file-class">Using a custom file class</a></p></li></ul></li><li><p><a href="#troubleshooting">Troubl
 eshooting</a></p><ul><li><p><a href="#mta-qmail">MTA: Qmail</a></p></li><li><p><a href="#mta-sendmail-relaying-denied">MTA: Sendmail relaying denied</a></p></li><li><p><a href="#imap-authentication-failed">IMAP: Authentication failed</a></p></li><li><p><a href="#imap-could-not-read-from-the-stream">IMAP: Could not read from the stream</a></p></li><li><p><a href="#parsing-iconv-notices">Parsing: iconv() notices</a></p></li><li><p><a href="#parsing-missing-characters">Parsing: missing characters</a></p></li><li><p><a href="#parsing-broken-headers">Parsing: broken headers</a></p></li><li><p><a href="#parsing-multiple-value-headers">Parsing: multiple-value headers</a></p></li><li><p><a href="#parsing-text-attachments-as-file-parts">Parsing: text attachments as file parts</a></p></li><li><p><a href="#parsing-attachment-file-names">Parsing: attachment file names</a></p></li></ul></li></ul></div><a name="introduction"></a><a name="id2"></a><h3>Introduction</h3><p>The Mail component
  provides functionality to send, retrieve and parse mail messages. If you require an easy way to send a mail, use the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> class, which allows you to send HTML mails with images, attachments and an optional text part. If you require more advanced mail messages, you can build the complete message yourself using the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailPart.html'>ezcMailPart</a> derived classes. You can retrieve mail messages from different sources using the supported transports.</p><a name="class-overview"></a><a name="id3"></a><h3>Class overview</h3><p>This section gives you an overview of the main classes in the Mail component.</p><dl><dt>ezcMailComposer</dt><dd>This is a convenience class that allows you to send plain text or HTML messages with attachments, without having to construct the parts of the message yourself. Most users will use this class.</dd
 ><dt>ezcMail</dt><dd>If <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> does not have the functionality you require, you can use the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> class to build MIME-structured mail from scratch. This requires basic knowledge about how a mail is structured.</dd><dt>ezcMailAddress</dt><dd>This small class represents a mail address with an optional name. It is used by both <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> and <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> to set recipient addresses.</dd><dt>ezcMailParser</dt><dd>This class parses mail messages from text into <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> structures. You can use it together with the mail retrieval transport classes.</dd><dt>ezcMailSmtpTransport</dt><dd>Send
 s mails using an SMTP server. After sending a mail, the connection can be kept alive so that the next mail sent uses the same connection, speeding up the process.</dd><dt>ezcMailMtaTransport</dt><dd>Sends mails using the PHP mail() function.</dd><dt>ezcMailPop3Transport</dt><dd>Connects to a POP3 server and allows the fetching and deleting of mails.</dd><dt>ezcMailImapTransport</dt><dd>Connects to an IMAP server and allows operations on mails in a mailbox (fetch, delete) and operations on mailboxes (create, delete, rename, append).</dd></dl><a name="usage"></a><a name="id4"></a><h3>Usage</h3><a name="transport-protocols"></a><a name="id5"></a><h4>Transport protocols</h4><p>The Mail component provides transport protocols for both sending and retrieving mail.</p><p>For sending mail, the following protocols are supported:</p><ul><li><p>SMTP (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailSmtpTransport.html'>ezcMailSmtpTransport</a>) - uses an SMTP server to sen
 d mail. Supports plain and TLS/SSL/SSLv2/SSLv3 connections.</p></li><li><p>MTA (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailMtaTransport.html'>ezcMailMtaTransport</a>) - wraps around the PHP mail() function.</p></li></ul><p>For mail retrieval we currently support the following protocols:</p><ul><li><p>POP3 (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailPop3Transport.html'>ezcMailPop3Transport</a>) - an old protocol but still used. SSL is supported.</p></li><li><p>IMAP (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailImapTransport.html'>ezcMailImapTransport</a>) - handles multiple mailboxes. SSL is supported.</p></li><li><p>MBOX (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailMboxTransport.html'>ezcMailMboxTransport</a>) - handles Unix mailbox file formats.</p></li></ul><p>Mail retrieval from other sources include:</p><ul><li><p>File (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailFileSet.
 html'>ezcMailFileSet</a>) - handles mails stored in files.</p></li><li><p>Variable (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailVariableSet.html'>ezcMailVariableSet</a>) - handles mails stored in memory.</p></li></ul><a name="mail-parsers"></a><a name="id6"></a><h4>Mail parsers</h4><p>After using a mail retrieval transport to fetch a set of mails, a mail parser can be used to go through the set and extract the needed information like subject, sender, date and attachments from each mail in the set. The <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailParser.html'>ezcMailParser</a> class is used for this purpose.</p><a name="mail-parts"></a><a name="id7"></a><h4>Mail parts</h4><p>The <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> component supports a wide variety of mail parts that can be used when sending or retrieving mails:</p><ul><li><p>ezcMailFile - mail attachment from an existing file</p></li><li><p>
 ezcMailStreamFile - mail attachment from an open stream</p></li><li><p>ezcMailVirtualFile - mail attachment from a string in memory</p></li><li><p>ezcMailMultipartAlternative - used to bundle a group of mail parts where only one should be shown</p></li><li><p>ezcMailMultipartDigest - used to bundle a list of mail objects</p></li><li><p>ezcMailMultipartMixed - used to bundle an ordered list of mail parts</p></li><li><p>ezcMailMultipartRelated - intended for mail parts consisting of several inter-related body parts</p></li><li><p>ezcMailMultipartReport - used for sending delivery status notifications</p></li><li><p>ezcMailDeliveryStatus - used for sending delivery status notifications</p></li><li><p>ezcMailRfc822Digest - used to insert another mail into a mail</p></li><li><p>ezcMailText - used for plain text</p></li></ul><a name="mail-tools"></a><a name="id8"></a><h4>Mail tools</h4><p>In the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailToo
 ls</a> class, you will find various useful static methods that can be used in your applications:</p><ul><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#lineBreak'>ezcMailTools::lineBreak</a>() - returns one end-of-line character (default \r\n). Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#setLineBreak'>ezcMailTools::setLineBreak</a>() to change the default</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#composeEmailAddress'>ezcMailTools::composeEmailAddress</a>() - returns the RFC822 representation of a mail address as a string. Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#composeEmailAddresses'>ezcMailTools::composeEmailAddresses</a>() for an array of mail address objects</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#parseEmailAddress'>ezcMailTools::parseEmailAddress</a>() - returns an <a 
 href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailAddress.html'>ezcMailAddress</a> object from a string mail address. Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#parseEmailAddresses'>ezcMailTools::parseEmailAddresses</a>() for a string of mail addresses</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#generateMessageId'>ezcMailTools::generateMessageId</a>() - returns a unique message ID to be used for a mail message</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#generateContentId'>ezcMailTools::generateContentId</a>() - returns a unique ID to be used for Content-ID headers</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#mimeDecode'>ezcMailTools::mimeDecode</a>() - decodes MIME-encoded fields and tries to recover from errors</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTool
 s.html#replyToMail'>ezcMailTools::replyToMail</a>() - returns a new <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> object that is a reply to the specified <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> object</p></li></ul><p>See the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> example below for information on how to use these methods.</p><a name="building-and-sending-mail"></a><a name="id9"></a><h3>Building and sending mail</h3><p>eZ components provides two ways to create mail. The simplest is to use the composer class <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a>. Using the composer you can send plain text messages, HTML messages with images and messages with attachments. If you require more advanced messages you can also customize them entirely by building it from the scratch using the various part type
 s in <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a>. The part types are structured the same way as the underlying mail MIME types.</p><a name="sending-a-mail-with-the-composer"></a><a name="id10"></a><h4>Sending a mail with the composer</h4><p>Sending a mail using the composer is very straightforward. This small example displays how to send a normal text message.</p><ol class="code">
+		<h2>eZ Components - Mail</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p></li><li><p><a href="#class-overview">Class overview</a></p></li><li><p><a href="#usage">Usage</a></p><ul><li><p><a href="#transport-protocols">Transport protocols</a></p></li><li><p><a href="#mail-parsers">Mail parsers</a></p></li><li><p><a href="#mail-parts">Mail parts</a></p></li><li><p><a href="#mail-tools">Mail tools</a></p></li></ul></li><li><p><a href="#building-and-sending-mail">Building and sending mail</a></p><ul><li><p><a href="#sending-a-mail-with-the-composer">Sending a mail with the composer</a></p></li><li><p><a href="#sending-a-mail-with-html-inline-images-and-attachments">Sending a mail with HTML, inline images and attachments</a></p></li><li><p><a href="#securing-html-mails-which-include-file-in-image-tags">Securing HTML mails which include file:// in image tags</a></p></li><li><p><a href="#building-a-mail-from-scratch">Building a
  mail from scratch</a></p></li><li><p><a href="#building-mime-structures-that-work">Building MIME structures that work</a></p></li><li><p><a href="#sending-a-mail-using-smtp">Sending a mail using SMTP</a></p></li><li><p><a href="#using-stronger-authentication-methods-with-the-smtp-transports">Using stronger authentication methods with the SMTP transports</a></p></li><li><p><a href="#avoid-bcc-headers-appearing-in-the-sent-mails">Avoid Bcc headers appearing in the sent mails</a></p></li><li><p><a href="#character-encoding">Character encoding</a></p></li><li><p><a href="#extending-the-mail-component">Extending the Mail component</a></p></li><li><p><a href="#using-the-ezcmailtools-class">Using the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> class</a></p></li></ul></li><li><p><a href="#mail-retrieval-and-parsing">Mail retrieval and parsing</a></p><ul><li><p><a href="#retrieving-mail-using-pop3">Retrieving mail using POP3</a></p></
 li><li><p><a href="#retrieving-mail-using-imap">Retrieving mail using IMAP</a></p></li><li><p><a href="#additional-usage-of-the-imap-transport">Additional usage of the IMAP transport</a></p></li><li><p><a href="#refering-messages-by-their-unique-ids-in-imap">Refering messages by their unique IDs in IMAP</a></p></li><li><p><a href="#working-with-transport-options">Working with transport options</a></p></li><li><p><a href="#using-ssl-with-pop3-and-imap">Using SSL with POP3 and IMAP</a></p></li><li><p><a href="#retrieving-mail-from-mbox-files">Retrieving mail from mbox files</a></p></li><li><p><a href="#parsing-a-message-set">Parsing a message set</a></p></li><li><p><a href="#displaying-html-mail-with-inline-images">Displaying HTML mail with inline images</a></p></li><li><p><a href="#using-a-custom-mail-class">Using a custom mail class</a></p></li><li><p><a href="#using-a-custom-file-class">Using a custom file class</a></p></li></ul></li><li><p><a href="#troubleshooting">Troubl
 eshooting</a></p><ul><li><p><a href="#mta-qmail">MTA: Qmail</a></p></li><li><p><a href="#mta-sendmail-relaying-denied">MTA: Sendmail relaying denied</a></p></li><li><p><a href="#imap-authentication-failed">IMAP: Authentication failed</a></p></li><li><p><a href="#imap-could-not-read-from-the-stream">IMAP: Could not read from the stream</a></p></li><li><p><a href="#parsing-iconv-notices">Parsing: iconv() notices</a></p></li><li><p><a href="#parsing-missing-characters">Parsing: missing characters</a></p></li><li><p><a href="#parsing-broken-headers">Parsing: broken headers</a></p></li><li><p><a href="#parsing-multiple-value-headers">Parsing: multiple-value headers</a></p></li><li><p><a href="#parsing-text-attachments-as-file-parts">Parsing: text attachments as file parts</a></p></li><li><p><a href="#parsing-attachment-file-names">Parsing: attachment file names</a></p></li></ul></li><li><p><a href="#security">Security</a></p><ul><li><p><a href="#excluding-the-user-agent-header">E
 xcluding the User-Agent header</a></p></li></ul></li></ul></div><a name="introduction"></a><a name="id2"></a><h3>Introduction</h3><p>The Mail component provides functionality to send, retrieve and parse mail messages. If you require an easy way to send a mail, use the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> class, which allows you to send HTML mails with images, attachments and an optional text part. If you require more advanced mail messages, you can build the complete message yourself using the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailPart.html'>ezcMailPart</a> derived classes. You can retrieve mail messages from different sources using the supported transports.</p><a name="class-overview"></a><a name="id3"></a><h3>Class overview</h3><p>This section gives you an overview of the main classes in the Mail component.</p><dl><dt>ezcMailComposer</dt><dd>This is a convenience class that allows you t
 o send plain text or HTML messages with attachments, without having to construct the parts of the message yourself. Most users will use this class.</dd><dt>ezcMail</dt><dd>If <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> does not have the functionality you require, you can use the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> class to build MIME-structured mail from scratch. This requires basic knowledge about how a mail is structured.</dd><dt>ezcMailAddress</dt><dd>This small class represents a mail address with an optional name. It is used by both <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a> and <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> to set recipient addresses.</dd><dt>ezcMailParser</dt><dd>This class parses mail messages from text into <a href='/zetacomponents/documentation/trunk/Mail/ph
 pdoc/ezcMail.html'>ezcMail</a> structures. You can use it together with the mail retrieval transport classes.</dd><dt>ezcMailSmtpTransport</dt><dd>Sends mails using an SMTP server. After sending a mail, the connection can be kept alive so that the next mail sent uses the same connection, speeding up the process.</dd><dt>ezcMailMtaTransport</dt><dd>Sends mails using the PHP mail() function.</dd><dt>ezcMailPop3Transport</dt><dd>Connects to a POP3 server and allows the fetching and deleting of mails.</dd><dt>ezcMailImapTransport</dt><dd>Connects to an IMAP server and allows operations on mails in a mailbox (fetch, delete) and operations on mailboxes (create, delete, rename, append).</dd></dl><a name="usage"></a><a name="id4"></a><h3>Usage</h3><a name="transport-protocols"></a><a name="id5"></a><h4>Transport protocols</h4><p>The Mail component provides transport protocols for both sending and retrieving mail.</p><p>For sending mail, the following protocols are supported:</p><ul>
 <li><p>SMTP (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailSmtpTransport.html'>ezcMailSmtpTransport</a>) - uses an SMTP server to send mail. Supports plain and TLS/SSL/SSLv2/SSLv3 connections.</p></li><li><p>MTA (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailMtaTransport.html'>ezcMailMtaTransport</a>) - wraps around the PHP mail() function.</p></li></ul><p>For mail retrieval we currently support the following protocols:</p><ul><li><p>POP3 (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailPop3Transport.html'>ezcMailPop3Transport</a>) - an old protocol but still used. SSL is supported.</p></li><li><p>IMAP (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailImapTransport.html'>ezcMailImapTransport</a>) - handles multiple mailboxes. SSL is supported.</p></li><li><p>MBOX (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailMboxTransport.html'>ezcMailMboxTransport</a>) - handles Unix mailbox file formats.<
 /p></li></ul><p>Mail retrieval from other sources include:</p><ul><li><p>File (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailFileSet.html'>ezcMailFileSet</a>) - handles mails stored in files.</p></li><li><p>Variable (<a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailVariableSet.html'>ezcMailVariableSet</a>) - handles mails stored in memory.</p></li></ul><a name="mail-parsers"></a><a name="id6"></a><h4>Mail parsers</h4><p>After using a mail retrieval transport to fetch a set of mails, a mail parser can be used to go through the set and extract the needed information like subject, sender, date and attachments from each mail in the set. The <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailParser.html'>ezcMailParser</a> class is used for this purpose.</p><a name="mail-parts"></a><a name="id7"></a><h4>Mail parts</h4><p>The <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> component supports a wide var
 iety of mail parts that can be used when sending or retrieving mails:</p><ul><li><p>ezcMailFile - mail attachment from an existing file</p></li><li><p>ezcMailStreamFile - mail attachment from an open stream</p></li><li><p>ezcMailVirtualFile - mail attachment from a string in memory</p></li><li><p>ezcMailMultipartAlternative - used to bundle a group of mail parts where only one should be shown</p></li><li><p>ezcMailMultipartDigest - used to bundle a list of mail objects</p></li><li><p>ezcMailMultipartMixed - used to bundle an ordered list of mail parts</p></li><li><p>ezcMailMultipartRelated - intended for mail parts consisting of several inter-related body parts</p></li><li><p>ezcMailMultipartReport - used for sending delivery status notifications</p></li><li><p>ezcMailDeliveryStatus - used for sending delivery status notifications</p></li><li><p>ezcMailRfc822Digest - used to insert another mail into a mail</p></li><li><p>ezcMailText - used for plain text</p></li></ul><a name
 ="mail-tools"></a><a name="id8"></a><h4>Mail tools</h4><p>In the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> class, you will find various useful static methods that can be used in your applications:</p><ul><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#lineBreak'>ezcMailTools::lineBreak</a>() - returns one end-of-line character (default \r\n). Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#setLineBreak'>ezcMailTools::setLineBreak</a>() to change the default</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#composeEmailAddress'>ezcMailTools::composeEmailAddress</a>() - returns the RFC822 representation of a mail address as a string. Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#composeEmailAddresses'>ezcMailTools::composeEmailAddresses</a>() for an array of mail address objects</p></li><li>
 <p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#parseEmailAddress'>ezcMailTools::parseEmailAddress</a>() - returns an <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailAddress.html'>ezcMailAddress</a> object from a string mail address. Use <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#parseEmailAddresses'>ezcMailTools::parseEmailAddresses</a>() for a string of mail addresses</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#generateMessageId'>ezcMailTools::generateMessageId</a>() - returns a unique message ID to be used for a mail message</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#generateContentId'>ezcMailTools::generateContentId</a>() - returns a unique ID to be used for Content-ID headers</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#mimeDecode'>ezcMailTools::mimeDecode</
 a>() - decodes MIME-encoded fields and tries to recover from errors</p></li><li><p><a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html#replyToMail'>ezcMailTools::replyToMail</a>() - returns a new <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> object that is a reply to the specified <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a> object</p></li></ul><p>See the <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTools.html'>ezcMailTools</a> example below for information on how to use these methods.</p><a name="building-and-sending-mail"></a><a name="id9"></a><h3>Building and sending mail</h3><p>eZ components provides two ways to create mail. The simplest is to use the composer class <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a>. Using the composer you can send plain text messages, HTML messages with images and messages w
 ith attachments. If you require more advanced messages you can also customize them entirely by building it from the scratch using the various part types in <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMail.html'>ezcMail</a>. The part types are structured the same way as the underlying mail MIME types.</p><a name="sending-a-mail-with-the-composer"></a><a name="id10"></a><h4>Sending a mail with the composer</h4><p>Sending a mail using the composer is very straightforward. This small example displays how to send a normal text message.</p><ol class="code">
 <li><span style="color: #000000">&lt;?php</span></li>
 <li><span style="color: #0000FF">require_once&nbsp;</span><span style="color: #335533">'tutorial_autoload.php'</span><span style="color: #0000FF">;</span></li>
 <li></li>
@@ -817,7 +817,9 @@ $parser-&gt;parseMail( $set );</code><a 
     "from localhost (localhost) by www.example.com..."
      );</code><p>instead of only the first value as a string if the second parameter to getHeader() was not specified.</p><a name="parsing-text-attachments-as-file-parts"></a><a name="id42"></a><h4>Parsing: text attachments as file parts</h4><p>By default, the mail parser creates <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailTextPart.html'>ezcMailTextPart</a> objects for text attachments found in the mail.</p><p>To create <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailFile.html'>ezcMailFile</a> objects instead (for example on servers where internal memory is limited), set this option to the mail parser before parsing:</p><code class="block">$parser = new <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailParser.html'>ezcMailParser</a>();
 $parser-&gt;options-&gt;parseTextAttachmentsAsFiles = true;
-// call $parser-&gt;parseMail( $set );</code><a name="parsing-attachment-file-names"></a><a name="id43"></a><h4>Parsing: attachment file names</h4><p>When parsing a mail with attachments you can use a code similar to the one in section . The mail part that contains the attachment ($part) has the <em>fileName</em> property which contains the raw file name, <em>contentDisposition-&gt;displayFileName</em> which contain the MIME-decoded file name. Use the <em>contentDisposition-&gt;displayFileName</em> value to copy the temporary files saved during parsing which contain the attachments, and which will not be available on the next request.</p><!--Local Variables:
+// call $parser-&gt;parseMail( $set );</code><a name="parsing-attachment-file-names"></a><a name="id43"></a><h4>Parsing: attachment file names</h4><p>When parsing a mail with attachments you can use a code similar to the one in section . The mail part that contains the attachment ($part) has the <em>fileName</em> property which contains the raw file name, <em>contentDisposition-&gt;displayFileName</em> which contain the MIME-decoded file name. Use the <em>contentDisposition-&gt;displayFileName</em> value to copy the temporary files saved during parsing which contain the attachments, and which will not be available on the next request.</p><a name="security"></a><a name="id44"></a><h3>Security</h3><a name="excluding-the-user-agent-header"></a><a name="id45"></a><h4>Excluding the User-Agent header</h4><p>By defaul the Mail component will add the "User-Agent" header containing the string "Apache Zeta Components". This can be considered a security issue. If you do not want to get
  this header sent along with the email you can use the following code:</p><code class="block">$mail = new <a href='/zetacomponents/documentation/trunk/Mail/phpdoc/ezcMailComposer.html'>ezcMailComposer</a>();
+// [...]
+$mail-&gt;appendExcludeHeaders(array('User-Agent'));</code><!--Local Variables:
 mode: rst
 fill-column: 79
 End:

Modified: incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.txt
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.txt?rev=1154102&r1=1154101&r2=1154102&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.txt (original)
+++ incubator/zetacomponents/website/htdocs/documentation/trunk/Mail/tutorial.txt Fri Aug  5 07:22:45 2011
@@ -686,6 +686,22 @@ available on the next request.
 .. _iconv: http://php.net/manual/en/function.iconv.php
 
 
+Security
+========
+
+Excluding the User-Agent header
+-------------------------------
+
+By defaul the Mail component will add the "User-Agent" header containing the
+string "Apache Zeta Components". This can be considered a security issue. If
+you do not want to get this header sent along with the email you can use the
+following code: ::
+
+    $mail = new ezcMailComposer();
+    // [...]
+    $mail->appendExcludeHeaders(array('User-Agent'));
+
+
 
 ..
    Local Variables:



Mime
View raw message