vendor/pear/net_smtp/docs/guide.txt

   1 ======================
   2  The Net_SMTP Package
   3 ======================
   4
   5 --------------------
   6  User Documentation
   7 --------------------
   8
   9 :Author:    Jon Parise
  10 :Contact:   jon@php.net
  11
  12 .. contents:: Table of Contents
  13 .. section-numbering::
  14
  15 Dependencies
  16 ============
  17
  18 The ``PEAR_Error`` Class
  19 ------------------------
  20
  21 The Net_SMTP package uses the `PEAR_Error`_ class for all of its `error
  22 handling`_.
  23
  24 The ``Net_Socket`` Package
  25 --------------------------
  26
  27 The Net_Socket_ package is used as the basis for all network communications.
  28 Connection options can be specified via the `$socket_options` construction
  29 parameter::
  30
  31     $socket_options = array('ssl' => array('verify_peer_name' => false));
  32     $smtp = new Net_SMTP($host, null, null, false, 0, $socket_options);
  33
  34 **Note:** PHP 5.6 introduced `OpenSSL changes`_. Peer certificate verification
  35 is now enabled by default. Although not recommended, `$socket_options` can be
  36 used to disable peer verification (as shown above).
  37
  38 .. _OpenSSL changes: http://php.net/manual/en/migration56.openssl.php
  39
  40 The ``Auth_SASL`` Package
  41 -------------------------
  42
  43 The `Auth_SASL`_ package is an optional dependency.  If it is available, the
  44 Net_SMTP package will be able to support the DIGEST-MD5_ and CRAM-MD5_ SMTP
  45 authentication methods.  Otherwise, only the LOGIN_ and PLAIN_ methods will
  46 be available.
  47
  48 Error Handling
  49 ==============
  50
  51 All of the Net_SMTP class's public methods return a PEAR_Error_ object if an
  52 error occurs.  The standard way to check for a PEAR_Error object is by using
  53 `PEAR::isError()`_::
  54
  55     if (PEAR::isError($error = $smtp->connect())) {
  56         die($error->getMessage());
  57     }
  58
  59 .. _PEAR::isError(): http://pear.php.net/manual/en/core.pear.pear.iserror.php
  60
  61 SMTP Authentication
  62 ===================
  63
  64 The Net_SMTP package supports the SMTP authentication standard (as defined
  65 by RFC-2554_).  The Net_SMTP package supports the following authentication
  66 methods, in order of preference:
  67
  68 .. _RFC-2554: http://www.ietf.org/rfc/rfc2554.txt
  69
  70 DIGEST-MD5
  71 ----------
  72
  73 The DIGEST-MD5 authentication method uses `RSA Data Security Inc.`_'s MD5
  74 Message Digest algorithm.  It is considered the most secure method of SMTP
  75 authentication.
  76
  77 **Note:** The DIGEST-MD5 authentication method is only supported if the
  78 AUTH_SASL_ package is available.
  79
  80 .. _RSA Data Security Inc.: http://www.rsasecurity.com/
  81
  82 CRAM-MD5
  83 --------
  84
  85 The CRAM-MD5 authentication method has been superseded by the DIGEST-MD5_
  86 method in terms of security.  It is provided here for compatibility with
  87 older SMTP servers that may not support the newer DIGEST-MD5 algorithm.
  88
  89 **Note:** The CRAM-MD5 authentication method is only supported if the
  90 AUTH_SASL_ package is available.
  91
  92 LOGIN
  93 -----
  94
  95 The LOGIN authentication method encrypts the user's password using the
  96 Base64_ encoding scheme.  Because decrypting a Base64-encoded string is
  97 trivial, LOGIN is not considered a secure authentication method and should
  98 be avoided.
  99
 100 .. _Base64: http://www.php.net/manual/en/function.base64-encode.php
 101
 102 PLAIN
 103 -----
 104
 105 The PLAIN authentication method sends the user's password in plain text.
 106 This method of authentication is not secure and should be avoided.
 107
 108 Secure Connections
 109 ==================
 110
 111 If `secure socket transports`_ have been enabled in PHP, it is possible to
 112 establish a secure connection to the remote SMTP server::
 113
 114     $smtp = new Net_SMTP('ssl://mail.example.com', 465);
 115
 116 This example connects to ``mail.example.com`` on port 465 (a common SMTPS
 117 port) using the ``ssl://`` transport.
 118
 119 .. _secure socket transports: http://www.php.net/transports
 120
 121 Sending Data
 122 ============
 123
 124 Message data is sent using the ``data()`` method.  The data can be supplied
 125 as a single string or as an open file resource.
 126
 127 If a string is provided, it is passed through the `data quoting`_ system and
 128 sent to the socket connection as a single block.  These operations are all
 129 memory-based, so sending large messages may result in high memory usage.
 130
 131 If an open file resource is provided, the ``data()`` method will read the
 132 message data from the file line-by-line.  Each chunk will be quoted and sent
 133 to the socket connection individually, reducing the overall memory overhead of
 134 this data sending operation.
 135
 136 Header data can be specified separately from message body data by passing it
 137 as the optional second parameter to ``data()``.  This is especially useful
 138 when an open file resource is being used to supply message data because it
 139 allows header fields (like *Subject:*) to be built dynamically at runtime.
 140
 141 ::
 142
 143     $smtp->data($fp, "Subject: My Subject");
 144
 145 Data Quoting
 146 ============
 147
 148 By default, all outbound string data is quoted in accordance with SMTP
 149 standards.  This means that all native Unix (``\n``) and Mac (``\r``) line
 150 endings are converted to Internet-standard CRLF (``\r\n``) line endings.
 151 Also, because the SMTP protocol uses a single leading period (``.``) to signal
 152 an end to the message data, single leading periods in the original data
 153 string are "doubled" (e.g. "``..``").
 154
 155 These string transformation can be expensive when large blocks of data are
 156 involved.  For example, the Net_SMTP package is not aware of MIME parts (it
 157 just sees the MIME message as one big string of characters), so it is not
 158 able to skip non-text attachments when searching for characters that may
 159 need to be quoted.
 160
 161 Because of this, it is possible to extend the Net_SMTP class in order to
 162 implement your own custom quoting routine.  Just create a new class based on
 163 the Net_SMTP class and reimplement the ``quotedata()`` method::
 164
 165     require 'Net_SMTP.php';
 166
 167     class Net_SMTP_custom extends Net_SMTP
 168     {
 169         function quotedata($data)
 170         {
 171             /* Perform custom data quoting */
 172         }
 173     }
 174
 175 Note that the ``$data`` parameter will be passed to the ``quotedata()``
 176 function `by reference`_.  This means that you can operate directly on
 177 ``$data``.  It also the overhead of copying a large ``$data`` string to and
 178 from the ``quotedata()`` method.
 179
 180 .. _by reference: http://www.php.net/manual/en/language.references.pass.php
 181
 182 Server Responses
 183 ================
 184
 185 The Net_SMTP package retains the server's last response for further
 186 inspection.  The ``getResponse()`` method returns a 2-tuple (two element
 187 array) containing the server's response code as an integer and the response's
 188 arguments as a string.
 189
 190 Upon a successful connection, the server's greeting string is available via
 191 the ``getGreeting()`` method.
 192
 193 Debugging
 194 =========
 195
 196 The Net_SMTP package contains built-in debugging output routines (disabled by
 197 default).  Debugging output must be explicitly enabled via the ``setDebug()``
 198 method::
 199
 200     $smtp->setDebug(true);
 201
 202 The debugging messages will be sent to the standard output stream by default.
 203 If you need more control over the output, you can optionally install your own
 204 debug handler.
 205
 206 ::
 207
 208     function debugHandler($smtp, $message)
 209     {
 210         echo "[$smtp->host] $message\n";
 211     }
 212
 213     $smtp->setDebug(true, "debugHandler");
 214
 215
 216 Examples
 217 ========
 218
 219 Basic Use
 220 ---------
 221
 222 The following script demonstrates how a simple email message can be sent
 223 using the Net_SMTP package::
 224
 225     require 'Net/SMTP.php';
 226
 227     $host = 'mail.example.com';
 228     $from = 'user@example.com';
 229     $rcpt = array('recipient1@example.com', 'recipient2@example.com');
 230     $subj = "Subject: Test Message\n";
 231     $body = "Body Line 1\nBody Line 2";
 232
 233     /* Create a new Net_SMTP object. */
 234     if (! ($smtp = new Net_SMTP($host))) {
 235         die("Unable to instantiate Net_SMTP object\n");
 236     }
 237
 238     /* Connect to the SMTP server. */
 239     if (PEAR::isError($e = $smtp->connect())) {
 240         die($e->getMessage() . "\n");
 241     }
 242
 243     /* Send the 'MAIL FROM:' SMTP command. */
 244     if (PEAR::isError($smtp->mailFrom($from))) {
 245         die("Unable to set sender to <$from>\n");
 246     }
 247
 248     /* Address the message to each of the recipients. */
 249     foreach ($rcpt as $to) {
 250         if (PEAR::isError($res = $smtp->rcptTo($to))) {
 251             die("Unable to add recipient <$to>: " . $res->getMessage() . "\n");
 252         }
 253     }
 254
 255     /* Set the body of the message. */
 256     if (PEAR::isError($smtp->data($subj . "\r\n" . $body))) {
 257         die("Unable to send data\n");
 258     }
 259
 260     /* Disconnect from the SMTP server. */
 261     $smtp->disconnect();
 262
 263 .. _PEAR_Error: http://pear.php.net/manual/en/core.pear.pear-error.php
 264 .. _Net_Socket: http://pear.php.net/package/Net_Socket
 265 .. _Auth_SASL: http://pear.php.net/package/Auth_SASL
 266
 267 .. vim: tabstop=4 shiftwidth=4 softtabstop=4 expandtab textwidth=78 ft=rst: