cvs: peardoc /en/core mail.xml
| From: | Martin Jansen | Date: | Sun, 06 Jan 2002 11:14:56 +0000 |
| Subject: | cvs: peardoc /en/core mail.xml | ||
| Groups: | php.pear.cvs | ||
| Request: | Send a blank email to pear-cvs+get-1850@lists.php.net to get a copy of this message | ||
mj Sun Jan 6 06:14:56 2002 EDT
Added files:
/peardoc/en/core mail.xml
Log:
* Add documentation for Mail package
Index: peardoc/en/core/mail.xml +++ peardoc/en/core/mail.xml <?xml encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <reference id="core.mail"> <title>PEAR Mail: Mail handling functions</title> <titleabbrev>Mail</titleabbrev> <partintro> <simpara> This chapter describes how to use the Mail functions that come with PEAR. </simpara> </partintro> <refentry id="core.mail.Mail"> <refnamediv> <refname>Mail</refname> <refpurpose>Provides an interface to the Mail:: classes.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> Provides an interface to the Mail:: classes. Also provides supporting functions useful in multiple mailer backends. </simpara> </refsect1> <refsect1> <title><function>Mail::factory</function></title> <simpara> This method is used to create a mail object from one of the driver classes in the Mail/ directory. It takes two arguments, the first being the driver type to use, and the second being an array of parameters to pass to the driver objects' constructor. </simpara> <programlisting role="php"> $params['host'] = 'localhost'; $params['port'] = 25; $mail_object =& Mail::factory('smtp', $params); </programlisting> <para> You can then call the <function>send</function> method of the $mail_object with the correct arguments (see the Mail_mail, Mail_smtp, Mail_sendmail docs). </para> </refsect1> </refentry> <refentry id="core.mail.phpmail"> <refnamediv> <refname>Mail/Mail.php</refname> <refpurpose>Sending mail using PHP's <function>mail</function></refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> A driver object providing the <function>send</function> method using PHP's <function>mail</function> function. </simpara> </refsect1> <refsect1> <title><function>send</function></title> <simpara> This method sends mail using the php built in <function> mail</function> function. As with the other driver functions it takes three arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$recipients</parameter> - An array or comma seperated string of recipients. </para> </listitem> <listitem> <para> <parameter>$headers</parameter> - An associative array of headers. Header name being the key, header value being the value. </para> </listitem> <listitem> <para> <parameter>$body</parameter> - Body of the email. </para> </listitem> </itemizedlist> </para> <programlisting role="php"> include('Mail.php'); $recipients = 'joe@example.com'; $headers['From'] = 'richard@phpguru.org'; $headers['To'] = 'joe@example.com'; $headers['Subject'] = 'Test message'; $body = 'Test message'; // Create the mail object using the Mail::factory method $mail_object =& Mail::factory('mail'); $mail_object->send($recipients, $headers, $body); </programlisting> </refsect1> </refentry> <refentry id="core.mail.sendmail"> <refnamediv> <refname>Mail/sendmail.php</refname> <refpurpose>Sending mail using a sendmail executable.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> A driver object providing the <function>send</function> method using a sendmail executable. </simpara> </refsect1> <refsect1> <title>constructor</title> <simpara> When creating the object using the $obj =& Mail::factory() syntax, the parameters passed to method are subsequently passed to this objects constructor. The possible parameters are: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$sendmail_path</parameter> - The path to the sendmail executable. Defaults to <filename>/usr/sbin/sendmail</filename>if not given. </para> </listitem> <listitem> <para> <parameter>$sendmail_args</parameter> - A string of extra arguments to pass to the sendmail executable. Defaults to blank if not given. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>send</function></title> <simpara> This method sends mail using a sendmail executable. As with the other driver functions it takes three arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$recipients</parameter> - An array or comma seperated string of recipients. </para> </listitem> <listitem> <para> <parameter>$headers</parameter> - An associative array of headers. Header name being the key, header value being the value. </para> </listitem> <listitem> <para> <parameter>$body</parameter> - Body of the email. </para> </listitem> </itemizedlist> </para> <programlisting role="php"> include('Mail.php'); $recipients = 'joe@example.com'; $headers['From'] = 'richard@phpguru.org'; $headers['To'] = 'joe@example.com'; $headers['Subject'] = 'Test message'; $body = 'Test message'; $params['sendmail_path'] = '/usr/lib/sendmail'; // Create the mail object using the Mail::factory method $mail_object =& Mail::factory('sendmail', $params); $mail_object->send($recipients, $headers, $body); </programlisting> </refsect1> </refentry> <refentry id="core.mail.smtp"> <refnamediv> <refname>Mail/smtp.php</refname> <refpurpose>Sending mail using SMTP.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> A driver object providing the <function>send</function> method using smtp. Utilises the <filename>Net/smtp.php</filename> and <filename>Net/socket.php</filename> classes to connect to the server. </simpara> </refsect1> <refsect1> <title>constructor</title> <simpara> When creating the object using the $obj =& Mail::factory() syntax, the parameters passed to method are subsequently passed to this objects constructor. The possible parameters are: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$host</parameter> - The smtp server to connect to. Either an IP address or hostname. Default if not given is localhost. </para> </listitem> <listitem> <para> <parameter>$port</parameter> - The port on which the smtp server runs. Default if not given is 25. </para> </listitem> <listitem> <para> <parameter>$auth</parameter> - Whether to use authentication or not. Default if not given is false. </para> </listitem> <listitem> <para> <parameter>$username</parameter> - Username to use in conjunction with authentication. Default if not given is blank. </para> </listitem> <listitem> <para> <parameter>$password</parameter> - Password to use in conjunction with authentication. Default if not given is blank. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>send</function></title> <simpara> This method sends mail using smtp. It uses the <filename> Net/Socket.php</filename> and <filename>Net/SMTP.php</filename> classes so ensure these are available. As with the other driver functions it takes three arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$recipients</parameter> - An array or comma seperated string of recipients. </para> </listitem> <listitem> <para> <parameter>$headers</parameter> - An associative array of headers. Header name being the key, header value being the value. </para> </listitem> <listitem> <para> <parameter>$body</parameter> - Body of the email. </para> </listitem> </itemizedlist> </para> <programlisting role="php"> include('Mail.php'); $recipients = 'joe@example.com'; $headers['From'] = 'richard@phpguru.org'; $headers['To'] = 'joe@example.com'; $headers['Subject'] = 'Test message'; $body = 'Test message'; $params['host'] = 'mail.example.com'; // Create the mail object using the Mail::factory method $mail_object =& Mail::factory('smtp', $params); $mail_object->send($recipients, $headers, $body); </programlisting> </refsect1> </refentry> <refentry id="core.mail.mime"> <refnamediv> <refname>Mail/mime.php</refname> <refpurpose>Class to create multipart messages.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> A class to enable easy creation of complex multipart emails. If what you're after is a simple API for creating such emails, then this class will probably suffice. If on the other hand you're after a higher degree of control over the email, then you might want to look at using <filename>mimePart.php</filename>. </simpara> </refsect1> <refsect1> <title>constructor</title> <simpara> The constructor takes only one argument, and that is the type of line end to use. The standard for this is CRLF, however *nix commonly uses LF and Macs CR. </simpara> </refsect1> <refsect1> <title><function>setTXTBody</function></title> <simpara> This function sets the plain text part of the email. It takes two arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$data</parameter> - Either the text to set, or a filename of a text file to use. </para> </listitem> <listitem> <para> <parameter>$isfile</parameter> - Optional. If true, then $data is assumed to be a filename and read in- </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>setHTMLBody</function></title> <simpara> This function sets the HTML part of the email. It takes two arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$data</parameter> - Either the HTML to set, or a filename of a text file to use. </para> </listitem> <listitem> <para> <parameter>$isfile</parameter> - Optional. If true, then $data is assumed to be a filename and read in- </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>setHTMLImage</function></title> <simpara> If sending an HTML email with embedded images, use this function to add the image. It takes four arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$file</parameter> - Either a filename or the actual file data itself. </para> </listitem> <listitem> <para> <parameter>$c_type</parameter> - The content type of the image/file. Defaults to application/octet-stream if not given. </para> </listitem> <listitem> <para> <parameter>$name</parameter> - The filename of the image/file. Defaults to blank if not given. </para> </listitem> <listitem> <para> <parameter>$isfilename</parameter> - Whether the $file argument is a filename or not. If true, the file will be read in Defaults to true if not given. </para> </listitem> </itemizedlist> </para> <para> <emphasis>Note:</emphasis> This function doesn't just enable you to embed images. Other file types, for example flash movies, can also be embedded. </para> </refsect1> <refsect1> <title><function>addAttachment</function></title> <simpara> Adds an attachment to the email. It takes five arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$file</parameter> - Either a filename or the actual file data itself. </para> </listitem> <listitem> <para> <parameter>$c_type</parameter> - Content type of the file. Defaults to application/octet-stream if not given. </para> </listitem> <listitem> <para> <parameter>$name</parameter> - The filename of the file. Defaults to blank if not given. </para> </listitem> <listitem> <para> <parameter>$isfilename</parameter> - Whether the $file argument is a filename or not. If true, the file will be read in Defaults to true if not given. </para> </listitem> <listitem> <para> <parameter>$encoding</parameter> - Type of transfer encoding to use for the file data. Defaults to base64 if not given For text based files (eg. scripts/html etc) this could be given as quoted-printable. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>get</function></title> <simpara> This function should be called once you have added the text/html/images/attachments. It builds the email and returns it. It does not send it. To send what this function returns (in conjunction with the headers() function) you would need to use one of the <link linkend="core.mail.phpmail">Mail_mail</link>, <link linkend="core.mail.sendmail">Mail_sendmail</link> or <link linkend="core.mail.smtp">Mail_smtp</link> classes described elsewhere in this documentation. It takes one argument only, which is an associative array of parameters. These parameters affect the way the email is built and can consist of: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$text_encoding</parameter> - Type of encoding to use for the plain text part of the email. Default is 7bit. </para> </listitem> <listitem> <para> <parameter>$html_encoding</parameter> - Type of encoding for the HTML part of the email. Default is quoted-printable. </para> </listitem> <listitem> <para> <parameter>$7bit_wrap</parameter> - Number of characters after which text is wrapped. SMTP stipulates maximum line length of 1000 characters including CRLF. Default is 998 (CRLF is appended to make up to 1000). </para> </listitem> <listitem> <para> <parameter>$text_charset</parameter> - The character set to use for the plain text part of the email. Default is iso-8859-1. </para> </listitem> <listitem> <para> <parameter>$html_charset</parameter> - The character set to use for the HTML part of the email. Default is iso-8859-1. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>headers</function></title> <simpara> This function returns appropriate headers needed for the email in the form of an associative array which you can pass directly to one of the Mail_mail, Mail_sendmail or Mail_smtp classes. It should be called after the call to <function>get</function>. This is because <function>get</function> generates some of the necessary headers. The function takes only one argument, which is an associative array of headers to also include in the returned array. The array keys should be the header names (eg. From, Subject, X-Mailer), whilst the values should be the header values. </simpara> </refsect1> <refsect1> <title>Example:</title> <programlisting role="php"> <![CDATA[ include('Mail.php'); include('Mail/mime.php'); $text = 'Text version of email'; $html = '<html><body>HTML version of email</body></html>'; $file = '/home/richard/example.php'; $crlf = "\r\n"; $hdrs = array( 'From' => 'richard@phpguru.org', 'Subject' => 'Test mime message' ); $mime = new Mail_mime($crlf); $mime->setTXTBody($text); $mime->setHTMLBody($html); $mime->addAttachment($file, 'text/plain'); $body =& $mime->get(); $hdrs =& $mime->headers($hdrs); $mail =& Mail::factory('mail'); $mail->send('joe@example.com', $hdrs, $body); ]]> </programlisting> </refsect1> </refentry> <refentry id="core.mail.mimeDecode"> <refnamediv> <refname>Mail/mimeDecode.php</refname> <refpurpose>Class to work with MIME messages.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> This class is a tool to help you work with mime emails/messages. It will take the input you give it and decode it into a usable PHP data structure. The data structure is an object with the following properties: </simpara> <para> <emphasis>headers:</emphasis> An associative array of the headers. The keys of the array are the header names (lowercased) whilst the values are the header values (original case). if there are multiple headers with the same name (eg. Recieved: ) then the value is a numerically indexed array of each of the header values. If the parameter decode_headers is specified as true, then the headers will be decoded (RFC2047). </para> <para> <emphasis>ctype_primary:</emphasis> The first part of the content type (ie. before the forward slash). Eg. If the content type is multipart/mixed, ctype_primary would be "multipart" (no quotes). </para> <para> <emphasis>ctype_secondary:</emphasis> The second part of the content type. Eg. If the content type is multipart/mixed, ctype_secondary would be "mixed" (no quotes). </para> <para> <emphasis>ctype_parameters:</emphasis> if the content type header has any parameters (eg. boundary="=_hudfhdsalfhds8fy8329hfj") then they will be in this associative array. Keys are the parameter name (eg. boundary) whilst the values are the parameter values (eg. =_hudfhdsalfhds8fy8329hfj ). </para> <para> <emphasis>disposition:</emphasis> if the Content-Disposition header is present, it's value will be given here. This is usually either "inline" or "attachment" (no quotes). </para> <para> <emphasis>d_parameters:</emphasis> if any parameters are given with the Content-Disposition header, they will be given here in an associative array, keys being the parameter names and values being the parameter values. "name" and "filename" are two common examples here. </para> <para> <emphasis>body:</emphasis> if the include_bodies parameter is given when instanciating the class, (either statically or normally), then this will be present if the part in question has a body. Mime parts with content type multipart/* generally do not not have bodies, instead consisting of subparts. If the parameter decode_bodies is specified as true then the body will be decoded. </para> <para> <emphasis>parts:</emphasis> if a mime part consists of subparts, then this array will be present consisting of objects with the same properties as described here. </para> </refsect1> <refsect1> <title><function>Mail_mimeDecode::constructor</function></title> <simpara> If instanciated as an object, the constructor takes two arguments: </simpara> <itemizedlist> <listitem> <para> <parameter>$input</parameter> - The email/message to decode. </para> </listitem> <listitem> <para> <parameter>$crlf</parameter> - Optional. This specifies the correct line ending to use. Usually either CRLF or just LF. This option can make the difference between this class working and not. You're strongly recommended to ensure you're email uses exclusively what this argument is set to. Default is CRLF. </para> </listitem> </itemizedlist> </refsect1> <refsect1> <title><function>Mail_mimeDecode::decode</function></title> <simpara> This function performs the decoding and returns the structure as detailed above. It takes just one argument which is an associative array of parameters. These parameters can consist of: </simpara> <itemizedlist> <listitem> <para> <parameter>$include_bodies</parameter> - Whether to include the bodies in the returned structure. </para> </listitem> <listitem> <para> <parameter>$decode_bodies</parameter> - Whether to decode the returned bodies. </para> </listitem> <listitem> <para> <parameter>$decode_headers</parameter> - Whether to decode the headers (RFC2047). </para> </listitem> <listitem> <para> <parameter>$input</parameter> - If and only if called statically, this should be used to specify the input to be decoded. </para> </listitem> <listitem> <para> <parameter>$crlf</parameter> - If and only if called statically, this should be used to specify the line ending type. </para> </listitem> </itemizedlist> </refsect1> <refsect1> <title><function>Mail_mimeDecode::uudecode</function></title> <simpara> This method is not called from the main decoding part of the class, but is included as it is a suitable location for it. Given some input it will check for any uuencoded attachments and return them in an associative array containing the file data, file perms and file name. It takes only one argument, that being the input to look at. This function can be called statically, even if you do not use the rest of the classes functionality. </simpara> </refsect1> <refsect1> <title><function>Mail_mimeDecode::getXML</function></title> <simpara> This method is not called from the main decoding part of the class. It takes the output returned by <function>decode</function> and converts it to XML using the DTD available here: http://www.phpguru.org/xmail/ or with the PEAR mime package (when it is available). The method takes only one argument, and that is the returned data from the <function>decode </function> method. </simpara> </refsect1> <refsect1> <title>Usage examples:</title> <simpara> This example instanciates the object normally and runs the decode function: </simpara> <programlisting role="php"> $params['include_bodies'] = TRUE; $params['decode_bodies'] = TRUE; $params['decode_headers'] = TRUE; $decoder = new Mail_mimeDecode($input); $structure = $decoder->decode($params); </programlisting> <para> This example calls the decode function statically (ie no object, straight function call) and then passes the structure to the <function>getXML</function> function. <programlisting role="php"> $params['include_bodies'] = TRUE; $params['decode_bodies'] = FALSE; $params['decode_headers'] = TRUE; $params['input'] = $input; $params['crlf'] = "\r\n"; $structure = Mail_mimeDecode::decode($params); $xml = Mail_mimeDecode::getXML($structure); </programlisting> </para> </refsect1> </refentry> </reference> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->
Index: peardoc/en/core/mail.xml +++ peardoc/en/core/mail.xml <?xml encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <reference id="core.mail"> <title>PEAR Mail: Mail handling functions</title> <titleabbrev>Mail</titleabbrev> <partintro> <simpara> This chapter describes how to use the Mail functions that come with PEAR. </simpara> </partintro> <refentry id="core.mail.Mail"> <refnamediv> <refname>Mail</refname> <refpurpose>Provides an interface to the Mail:: classes.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> Provides an interface to the Mail:: classes. Also provides supporting functions useful in multiple mailer backends. </simpara> </refsect1> <refsect1> <title><function>Mail::factory</function></title> <simpara> This method is used to create a mail object from one of the driver classes in the Mail/ directory. It takes two arguments, the first being the driver type to use, and the second being an array of parameters to pass to the driver objects' constructor. </simpara> <programlisting role="php"> $params['host'] = 'localhost'; $params['port'] = 25; $mail_object =& Mail::factory('smtp', $params); </programlisting> <para> You can then call the <function>send</function> method of the $mail_object with the correct arguments (see the Mail_mail, Mail_smtp, Mail_sendmail docs). </para> </refsect1> </refentry> <refentry id="core.mail.phpmail"> <refnamediv> <refname>Mail/Mail.php</refname> <refpurpose>Sending mail using PHP's <function>mail</function></refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> A driver object providing the <function>send</function> method using PHP's <function>mail</function> function. </simpara> </refsect1> <refsect1> <title><function>send</function></title> <simpara> This method sends mail using the php built in <function> mail</function> function. As with the other driver functions it takes three arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$recipients</parameter> - An array or comma seperated string of recipients. </para> </listitem> <listitem> <para> <parameter>$headers</parameter> - An associative array of headers. Header name being the key, header value being the value. </para> </listitem> <listitem> <para> <parameter>$body</parameter> - Body of the email. </para> </listitem> </itemizedlist> </para> <programlisting role="php"> include('Mail.php'); $recipients = 'joe@example.com'; $headers['From'] = 'richard@phpguru.org'; $headers['To'] = 'joe@example.com'; $headers['Subject'] = 'Test message'; $body = 'Test message'; // Create the mail object using the Mail::factory method $mail_object =& Mail::factory('mail'); $mail_object->send($recipients, $headers, $body); </programlisting> </refsect1> </refentry> <refentry id="core.mail.sendmail"> <refnamediv> <refname>Mail/sendmail.php</refname> <refpurpose>Sending mail using a sendmail executable.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> A driver object providing the <function>send</function> method using a sendmail executable. </simpara> </refsect1> <refsect1> <title>constructor</title> <simpara> When creating the object using the $obj =& Mail::factory() syntax, the parameters passed to method are subsequently passed to this objects constructor. The possible parameters are: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$sendmail_path</parameter> - The path to the sendmail executable. Defaults to <filename>/usr/sbin/sendmail</filename>if not given. </para> </listitem> <listitem> <para> <parameter>$sendmail_args</parameter> - A string of extra arguments to pass to the sendmail executable. Defaults to blank if not given. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>send</function></title> <simpara> This method sends mail using a sendmail executable. As with the other driver functions it takes three arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$recipients</parameter> - An array or comma seperated string of recipients. </para> </listitem> <listitem> <para> <parameter>$headers</parameter> - An associative array of headers. Header name being the key, header value being the value. </para> </listitem> <listitem> <para> <parameter>$body</parameter> - Body of the email. </para> </listitem> </itemizedlist> </para> <programlisting role="php"> include('Mail.php'); $recipients = 'joe@example.com'; $headers['From'] = 'richard@phpguru.org'; $headers['To'] = 'joe@example.com'; $headers['Subject'] = 'Test message'; $body = 'Test message'; $params['sendmail_path'] = '/usr/lib/sendmail'; // Create the mail object using the Mail::factory method $mail_object =& Mail::factory('sendmail', $params); $mail_object->send($recipients, $headers, $body); </programlisting> </refsect1> </refentry> <refentry id="core.mail.smtp"> <refnamediv> <refname>Mail/smtp.php</refname> <refpurpose>Sending mail using SMTP.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> A driver object providing the <function>send</function> method using smtp. Utilises the <filename>Net/smtp.php</filename> and <filename>Net/socket.php</filename> classes to connect to the server. </simpara> </refsect1> <refsect1> <title>constructor</title> <simpara> When creating the object using the $obj =& Mail::factory() syntax, the parameters passed to method are subsequently passed to this objects constructor. The possible parameters are: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$host</parameter> - The smtp server to connect to. Either an IP address or hostname. Default if not given is localhost. </para> </listitem> <listitem> <para> <parameter>$port</parameter> - The port on which the smtp server runs. Default if not given is 25. </para> </listitem> <listitem> <para> <parameter>$auth</parameter> - Whether to use authentication or not. Default if not given is false. </para> </listitem> <listitem> <para> <parameter>$username</parameter> - Username to use in conjunction with authentication. Default if not given is blank. </para> </listitem> <listitem> <para> <parameter>$password</parameter> - Password to use in conjunction with authentication. Default if not given is blank. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>send</function></title> <simpara> This method sends mail using smtp. It uses the <filename> Net/Socket.php</filename> and <filename>Net/SMTP.php</filename> classes so ensure these are available. As with the other driver functions it takes three arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$recipients</parameter> - An array or comma seperated string of recipients. </para> </listitem> <listitem> <para> <parameter>$headers</parameter> - An associative array of headers. Header name being the key, header value being the value. </para> </listitem> <listitem> <para> <parameter>$body</parameter> - Body of the email. </para> </listitem> </itemizedlist> </para> <programlisting role="php"> include('Mail.php'); $recipients = 'joe@example.com'; $headers['From'] = 'richard@phpguru.org'; $headers['To'] = 'joe@example.com'; $headers['Subject'] = 'Test message'; $body = 'Test message'; $params['host'] = 'mail.example.com'; // Create the mail object using the Mail::factory method $mail_object =& Mail::factory('smtp', $params); $mail_object->send($recipients, $headers, $body); </programlisting> </refsect1> </refentry> <refentry id="core.mail.mime"> <refnamediv> <refname>Mail/mime.php</refname> <refpurpose>Class to create multipart messages.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> A class to enable easy creation of complex multipart emails. If what you're after is a simple API for creating such emails, then this class will probably suffice. If on the other hand you're after a higher degree of control over the email, then you might want to look at using <filename>mimePart.php</filename>. </simpara> </refsect1> <refsect1> <title>constructor</title> <simpara> The constructor takes only one argument, and that is the type of line end to use. The standard for this is CRLF, however *nix commonly uses LF and Macs CR. </simpara> </refsect1> <refsect1> <title><function>setTXTBody</function></title> <simpara> This function sets the plain text part of the email. It takes two arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$data</parameter> - Either the text to set, or a filename of a text file to use. </para> </listitem> <listitem> <para> <parameter>$isfile</parameter> - Optional. If true, then $data is assumed to be a filename and read in- </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>setHTMLBody</function></title> <simpara> This function sets the HTML part of the email. It takes two arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$data</parameter> - Either the HTML to set, or a filename of a text file to use. </para> </listitem> <listitem> <para> <parameter>$isfile</parameter> - Optional. If true, then $data is assumed to be a filename and read in- </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>setHTMLImage</function></title> <simpara> If sending an HTML email with embedded images, use this function to add the image. It takes four arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$file</parameter> - Either a filename or the actual file data itself. </para> </listitem> <listitem> <para> <parameter>$c_type</parameter> - The content type of the image/file. Defaults to application/octet-stream if not given. </para> </listitem> <listitem> <para> <parameter>$name</parameter> - The filename of the image/file. Defaults to blank if not given. </para> </listitem> <listitem> <para> <parameter>$isfilename</parameter> - Whether the $file argument is a filename or not. If true, the file will be read in Defaults to true if not given. </para> </listitem> </itemizedlist> </para> <para> <emphasis>Note:</emphasis> This function doesn't just enable you to embed images. Other file types, for example flash movies, can also be embedded. </para> </refsect1> <refsect1> <title><function>addAttachment</function></title> <simpara> Adds an attachment to the email. It takes five arguments: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$file</parameter> - Either a filename or the actual file data itself. </para> </listitem> <listitem> <para> <parameter>$c_type</parameter> - Content type of the file. Defaults to application/octet-stream if not given. </para> </listitem> <listitem> <para> <parameter>$name</parameter> - The filename of the file. Defaults to blank if not given. </para> </listitem> <listitem> <para> <parameter>$isfilename</parameter> - Whether the $file argument is a filename or not. If true, the file will be read in Defaults to true if not given. </para> </listitem> <listitem> <para> <parameter>$encoding</parameter> - Type of transfer encoding to use for the file data. Defaults to base64 if not given For text based files (eg. scripts/html etc) this could be given as quoted-printable. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>get</function></title> <simpara> This function should be called once you have added the text/html/images/attachments. It builds the email and returns it. It does not send it. To send what this function returns (in conjunction with the headers() function) you would need to use one of the <link linkend="core.mail.phpmail">Mail_mail</link>, <link linkend="core.mail.sendmail">Mail_sendmail</link> or <link linkend="core.mail.smtp">Mail_smtp</link> classes described elsewhere in this documentation. It takes one argument only, which is an associative array of parameters. These parameters affect the way the email is built and can consist of: </simpara> <para> <itemizedlist> <listitem> <para> <parameter>$text_encoding</parameter> - Type of encoding to use for the plain text part of the email. Default is 7bit. </para> </listitem> <listitem> <para> <parameter>$html_encoding</parameter> - Type of encoding for the HTML part of the email. Default is quoted-printable. </para> </listitem> <listitem> <para> <parameter>$7bit_wrap</parameter> - Number of characters after which text is wrapped. SMTP stipulates maximum line length of 1000 characters including CRLF. Default is 998 (CRLF is appended to make up to 1000). </para> </listitem> <listitem> <para> <parameter>$text_charset</parameter> - The character set to use for the plain text part of the email. Default is iso-8859-1. </para> </listitem> <listitem> <para> <parameter>$html_charset</parameter> - The character set to use for the HTML part of the email. Default is iso-8859-1. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title><function>headers</function></title> <simpara> This function returns appropriate headers needed for the email in the form of an associative array which you can pass directly to one of the Mail_mail, Mail_sendmail or Mail_smtp classes. It should be called after the call to <function>get</function>. This is because <function>get</function> generates some of the necessary headers. The function takes only one argument, which is an associative array of headers to also include in the returned array. The array keys should be the header names (eg. From, Subject, X-Mailer), whilst the values should be the header values. </simpara> </refsect1> <refsect1> <title>Example:</title> <programlisting role="php"> <![CDATA[ include('Mail.php'); include('Mail/mime.php'); $text = 'Text version of email'; $html = '<html><body>HTML version of email</body></html>'; $file = '/home/richard/example.php'; $crlf = "\r\n"; $hdrs = array( 'From' => 'richard@phpguru.org', 'Subject' => 'Test mime message' ); $mime = new Mail_mime($crlf); $mime->setTXTBody($text); $mime->setHTMLBody($html); $mime->addAttachment($file, 'text/plain'); $body =& $mime->get(); $hdrs =& $mime->headers($hdrs); $mail =& Mail::factory('mail'); $mail->send('joe@example.com', $hdrs, $body); ]]> </programlisting> </refsect1> </refentry> <refentry id="core.mail.mimeDecode"> <refnamediv> <refname>Mail/mimeDecode.php</refname> <refpurpose>Class to work with MIME messages.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> This class is a tool to help you work with mime emails/messages. It will take the input you give it and decode it into a usable PHP data structure. The data structure is an object with the following properties: </simpara> <para> <emphasis>headers:</emphasis> An associative array of the headers. The keys of the array are the header names (lowercased) whilst the values are the header values (original case). if there are multiple headers with the same name (eg. Recieved: ) then the value is a numerically indexed array of each of the header values. If the parameter decode_headers is specified as true, then the headers will be decoded (RFC2047). </para> <para> <emphasis>ctype_primary:</emphasis> The first part of the content type (ie. before the forward slash). Eg. If the content type is multipart/mixed, ctype_primary would be "multipart" (no quotes). </para> <para> <emphasis>ctype_secondary:</emphasis> The second part of the content type. Eg. If the content type is multipart/mixed, ctype_secondary would be "mixed" (no quotes). </para> <para> <emphasis>ctype_parameters:</emphasis> if the content type header has any parameters (eg. boundary="=_hudfhdsalfhds8fy8329hfj") then they will be in this associative array. Keys are the parameter name (eg. boundary) whilst the values are the parameter values (eg. =_hudfhdsalfhds8fy8329hfj ). </para> <para> <emphasis>disposition:</emphasis> if the Content-Disposition header is present, it's value will be given here. This is usually either "inline" or "attachment" (no quotes). </para> <para> <emphasis>d_parameters:</emphasis> if any parameters are given with the Content-Disposition header, they will be given here in an associative array, keys being the parameter names and values being the parameter values. "name" and "filename" are two common examples here. </para> <para> <emphasis>body:</emphasis> if the include_bodies parameter is given when instanciating the class, (either statically or normally), then this will be present if the part in question has a body. Mime parts with content type multipart/* generally do not not have bodies, instead consisting of subparts. If the parameter decode_bodies is specified as true then the body will be decoded. </para> <para> <emphasis>parts:</emphasis> if a mime part consists of subparts, then this array will be present consisting of objects with the same properties as described here. </para> </refsect1> <refsect1> <title><function>Mail_mimeDecode::constructor</function></title> <simpara> If instanciated as an object, the constructor takes two arguments: </simpara> <itemizedlist> <listitem> <para> <parameter>$input</parameter> - The email/message to decode. </para> </listitem> <listitem> <para> <parameter>$crlf</parameter> - Optional. This specifies the correct line ending to use. Usually either CRLF or just LF. This option can make the difference between this class working and not. You're strongly recommended to ensure you're email uses exclusively what this argument is set to. Default is CRLF. </para> </listitem> </itemizedlist> </refsect1> <refsect1> <title><function>Mail_mimeDecode::decode</function></title> <simpara> This function performs the decoding and returns the structure as detailed above. It takes just one argument which is an associative array of parameters. These parameters can consist of: </simpara> <itemizedlist> <listitem> <para> <parameter>$include_bodies</parameter> - Whether to include the bodies in the returned structure. </para> </listitem> <listitem> <para> <parameter>$decode_bodies</parameter> - Whether to decode the returned bodies. </para> </listitem> <listitem> <para> <parameter>$decode_headers</parameter> - Whether to decode the headers (RFC2047). </para> </listitem> <listitem> <para> <parameter>$input</parameter> - If and only if called statically, this should be used to specify the input to be decoded. </para> </listitem> <listitem> <para> <parameter>$crlf</parameter> - If and only if called statically, this should be used to specify the line ending type. </para> </listitem> </itemizedlist> </refsect1> <refsect1> <title><function>Mail_mimeDecode::uudecode</function></title> <simpara> This method is not called from the main decoding part of the class, but is included as it is a suitable location for it. Given some input it will check for any uuencoded attachments and return them in an associative array containing the file data, file perms and file name. It takes only one argument, that being the input to look at. This function can be called statically, even if you do not use the rest of the classes functionality. </simpara> </refsect1> <refsect1> <title><function>Mail_mimeDecode::getXML</function></title> <simpara> This method is not called from the main decoding part of the class. It takes the output returned by <function>decode</function> and converts it to XML using the DTD available here: http://www.phpguru.org/xmail/ or with the PEAR mime package (when it is available). The method takes only one argument, and that is the returned data from the <function>decode </function> method. </simpara> </refsect1> <refsect1> <title>Usage examples:</title> <simpara> This example instanciates the object normally and runs the decode function: </simpara> <programlisting role="php"> $params['include_bodies'] = TRUE; $params['decode_bodies'] = TRUE; $params['decode_headers'] = TRUE; $decoder = new Mail_mimeDecode($input); $structure = $decoder->decode($params); </programlisting> <para> This example calls the decode function statically (ie no object, straight function call) and then passes the structure to the <function>getXML</function> function. <programlisting role="php"> $params['include_bodies'] = TRUE; $params['decode_bodies'] = FALSE; $params['decode_headers'] = TRUE; $params['input'] = $input; $params['crlf'] = "\r\n"; $structure = Mail_mimeDecode::decode($params); $xml = Mail_mimeDecode::getXML($structure); </programlisting> </para> </refsect1> </refentry> </reference> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->