Mercurial > hg > rc1

comparison vendor/pear/net_smtp/docs/guide.txt @ 0:1e000243b222

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
vanilla 1.3.3 distro, I hope
author Charlie Root
date Thu, 04 Jan 2018 15:50:29 -0500
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:1e000243b222
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: