wikia / net_smtp2
An implementation of the SMTP protocol
Requires
Requires (Dev)
Suggests
- pear/auth_sasl: Install optionally via your project's composer.json
This package is auto-updated.
Last update: 2024-10-27 21:56:26 UTC
README
1 The Net_SMTP2 Package
1.1 User Documentation
Table of Contents
- 1 The Net_SMTP2 Package
1.1.1 Dependencies
1.1.1.1 The PEAR_Exception
Class
The Net_SMTP2 package uses the PEAR_Exception object for all of its error handling.
1.1.1.2 The Net_Socket
Package
The Net_Socket package is used as the basis for all network communications.
1.1.1.3 The Auth_SASL
Package
The Auth_SASL package is an optional dependency. If it is available, the Net_SMTP2 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.
1.1.2 Error Handling
All of the Net_SMTP2 class's public methods throw a PEAR_Exception object if an error occurs. The standard way to check for a PEAR_Error object is by using try/catch blocks:
try { $smtp->connect(); } catch (PEAR_Exception $e) { die($e->getMessage()); }
1.1.3 SMTP Authentication
The Net_SMTP2 package supports the SMTP authentication standard (as defined by RFC-2554). The Net_SMTP2 package supports the following authentication methods, in order of preference:
1.1.3.1 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.
1.1.3.2 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.
1.1.3.3 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.
1.1.3.4 PLAIN
The PLAIN authentication method sends the user's password in plain text. This method of authentication is not secure and should be avoided.
1.1.4 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_SMTP2('ssl://mail.example.com', 465);
This example connects to mail.example.com
on port 465 (a common SMTPS
port) using the ssl://
transport.
1.1.5 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");
1.1.6 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_SMTP2 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_SMTP2 class in order to
implement your own custom quoting routine. Just create a new class based on
the Net_SMTP2 class and reimplement the quotedata()
method:
require 'Net/SMTP2.php'; class Net_SMTP2_custom extends Net_SMTP2 { 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.
1.1.7 Server Responses
The Net_SMTP2 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.
1.1.8 Debugging
The Net_SMTP2 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");
1.1.9 Examples
1.1.9.1 Basic Use
The following script demonstrates how a simple email message can be sent using the Net_SMTP2 package:
require 'Net/SMTP2.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_SMTP2 object. */ if (! ($smtp = new Net_SMTP2($host))) { die("Unable to instantiate Net_SMTP2 object\n"); } /* Connect to the SMTP server. */ try { $smtp->connect(); } catch (PEAR_Exception $e) { die($e->getMessage() . "\n"); } /* Send the 'MAIL FROM:' SMTP command. */ try { $smtp->mailFrom($from); } catch (PEAR_Exception $e) { die("Unable to set sender to <$from>\n"); } /* Address the message to each of the recipients. */ try { foreach ($rcpt as $to) { $smtp->rcptTo($to); } } catch (PEAR_Exception $e) { die("Unable to add recipient <$to>: " . $e->getMessage() . "\n"); } /* Set the body of the message. */ try { $smtp->data($subj . "\r\n" . $body); } catch (PEAR_Exception $e) { die("Unable to send data\n"); } /* Disconnect from the SMTP server. */ $smtp->disconnect();