|
0
|
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:
|
