====================== The Net_SMTP Package ====================== -------------------- User Documentation -------------------- :Author: Jon Parise :Contact: jon@php.net :Date: $Date: 2005/03/04 03:35:45 $ :Revision: $Revision: 1.5 $ .. contents:: Table of Contents .. section-numbering:: Dependencies ============ The `PEAR_Error` Class ---------------------- The Net_SMTP package uses the `PEAR_Error`_ class for all of its `error handling`_. The `Net_Socket` Package ------------------------ The Net_Socket_ package is used as the basis for all network communications. The `Auth_SASL` Package ----------------------- The `Auth_SASL`_ package is an optional dependency. If it is available, the Net_SMTP package will be able to support the DIGEST-MD5_ and CRAM-MD5_ SMTP authentication methods. Otherwise, only the LOGIN_ and PLAIN_ methods will be available. Error Handling ============== All of the Net_SMTP class's public methods return a PEAR_Error_ object if an error occurs. The standard way to check for a PEAR_Error object is by using `PEAR::isError()`_:: if (PEAR::isError($error = $smtp->connect())) { die($error->getMessage()); } .. _PEAR::isError(): http://pear.php.net/manual/en/core.pear.pear.iserror.php SMTP Authentication =================== The Net_SMTP package supports the SMTP authentication standard (as defined by RFC-2554_). The Net_SMTP package supports the following authentication methods, in order of preference: .. _RFC-2554: http://www.ietf.org/rfc/rfc2554.txt DIGEST-MD5 ---------- The DIGEST-MD5 authentication method uses `RSA Data Security Inc.`_'s MD5 Message Digest algorithm. It is considered the most secure method of SMTP authentication. **Note:** The DIGEST-MD5 authentication method is only supported if the AUTH_SASL_ package is available. .. _RSA Data Security Inc.: http://www.rsasecurity.com/ CRAM-MD5 -------- The CRAM-MD5 authentication method has been superseded by the DIGEST-MD5_ method in terms of security. It is provided here for compatibility with older SMTP servers that may not support the newer DIGEST-MD5 algorithm. **Note:** The CRAM-MD5 authentication method is only supported if the AUTH_SASL_ package is available. LOGIN ----- The LOGIN authentication method encrypts the user's password using the Base64_ encoding scheme. Because decrypting a Base64-encoded string is trivial, LOGIN is not considered a secure authentication method and should be avoided. .. _Base64: http://www.php.net/manual/en/function.base64-encode.php PLAIN ----- The PLAIN authentication method sends the user's password in plain text. This method of authentication is not secure and should be avoided. Secure Connections ================== If `secure socket transports`_ have been enabled in PHP, it is possible to establish a secure connection to the remote SMTP server:: $smtp = new Net_SMTP('ssl://mail.example.com', 465); This example connects to `mail.example.com` on port 465 (a common SMTPS port) using the `ssl://` transport. .. _secure socket transports: http://www.php.net/transports Data Quoting ============ By default, all outbound string data is quoted in accordance with SMTP standards. This means that all native Unix (`\\n`) and Mac (`\\r`) line endings are converted to Internet-standard CRLF (`\\r\\n`) line endings. Also, because the SMTP protocol uses a single leading period (`.`) to signal an end to the message data, single leading periods in the original data string are "doubled" (e.g. "`..`"). These string transformation can be expensive when large blocks of data are involved. For example, the Net_SMTP package is not aware of MIME parts (it just sees the MIME message as one big string of characters), so it is not able to skip non-text attachments when searching for characters that may need to be quoted. Because of this, it is possible to extend the Net_SMTP class in order to implement your own custom quoting routine. Just create a new class based on the Net_SMTP class and reimplement the `quotedata()` method:: require 'Net_SMTP.php'; class Net_SMTP_custom extends Net_SMTP { function quotedata($data) { /* Perform custom data quoting */ } } Note that the `$data` parameter will be passed to the `quotedata()` function `by reference`_. This means that you can operate directly on `$data`. It also the overhead of copying a large `$data` string to and from the `quotedata()` method. .. _by reference: http://www.php.net/manual/en/language.references.pass.php Debugging ========= The Net_SMTP package contains built-in debugging output routines (disabled by default). Debugging output must be explicitly enabled via the setDebug() method:: $smtp->setDebug(true); The debugging messages will be sent to the standard output stream. Examples ======== Basic Use --------- The following script demonstrates how a simple email message can be sent using the Net_SMTP package:: require 'Net/SMTP.php'; $host = 'mail.example.com'; $from = 'user@example.com'; $rcpt = array('recipient1@example.com', 'recipient2@example.com'); $subj = "Subject: Test Message\n"; $body = "Body Line 1\nBody Line 2"; /* Create a new Net_SMTP object. */ if (! ($smtp = new Net_SMTP($host))) { die("Unable to instantiate Net_SMTP object\n"); } /* Connect to the SMTP server. */ if (PEAR::isError($e = $smtp->connect())) { die($e->getMessage() . "\n"); } /* Send the 'MAIL FROM:' SMTP command. */ if (PEAR::isError($smtp->mailFrom($from))) { die("Unable to set sender to <$from>\n"); } /* Address the message to each of the recipients. */ foreach ($rcpt as $to) { if (PEAR::isError($res = $smtp->rcptTo($to))) { die("Unable to add recipient <$to>: " . $res->getMessage() . "\n"); } } /* Set the body of the message. */ if (PEAR::isError($smtp->data($subj . "\r\n" . $body))) { die("Unable to send data\n"); } /* Disconnect from the SMTP server. */ $smtp->disconnect(); .. _PEAR_Error: http://pear.php.net/manual/en/core.pear.pear-error.php .. _Net_Socket: http://pear.php.net/package/Net_Socket .. _Auth_SASL: http://pear.php.net/package/Auth_SASL .. vim: tabstop=4 shiftwidth=4 softtabstop=4 expandtab textwidth=76: