--- /dev/null
+======================
+ The Net_SMTP Package
+======================
+
+--------------------
+ User Documentation
+--------------------
+
+:Author: Jon Parise
+:Contact: jon@php.net
+
+.. 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.
+Connection options can be specified via the `$socket_options` construction
+parameter::
+
+ $socket_options = array('ssl' => array('verify_peer_name' => false));
+ $smtp = new Net_SMTP($host, null, null, false, 0, $socket_options);
+
+**Note:** PHP 5.6 introduced `OpenSSL changes`_. Peer certificate verification
+is now enabled by default. Although not recommended, `$socket_options` can be
+used to disable peer verification (as shown above).
+
+.. _OpenSSL changes: http://php.net/manual/en/migration56.openssl.php
+
+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
+
+Sending Data
+============
+
+Message data is sent using the ``data()`` method. The data can be supplied
+as a single string or as an open file resource.
+
+If a string is provided, it is passed through the `data quoting`_ system and
+sent to the socket connection as a single block. These operations are all
+memory-based, so sending large messages may result in high memory usage.
+
+If an open file resource is provided, the ``data()`` method will read the
+message data from the file line-by-line. Each chunk will be quoted and sent
+to the socket connection individually, reducing the overall memory overhead of
+this data sending operation.
+
+Header data can be specified separately from message body data by passing it
+as the optional second parameter to ``data()``. This is especially useful
+when an open file resource is being used to supply message data because it
+allows header fields (like *Subject:*) to be built dynamically at runtime.
+
+::
+
+ $smtp->data($fp, "Subject: My Subject");
+
+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
+
+Server Responses
+================
+
+The Net_SMTP package retains the server's last response for further
+inspection. The ``getResponse()`` method returns a 2-tuple (two element
+array) containing the server's response code as an integer and the response's
+arguments as a string.
+
+Upon a successful connection, the server's greeting string is available via
+the ``getGreeting()`` method.
+
+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 by default.
+If you need more control over the output, you can optionally install your own
+debug handler.
+
+::
+
+ function debugHandler($smtp, $message)
+ {
+ echo "[$smtp->host] $message\n";
+ }
+
+ $smtp->setDebug(true, "debugHandler");
+
+
+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=78 ft=rst:
scripts.mit.edu / autoinstallsdev / mediawiki.git / blobdiff