Mail_smtp Class Reference

Inheritance diagram for Mail_smtp:

Collaboration diagram for Mail_smtp:

Public Member Functions
	Mail_smtp ($params)
	Constructor.
	_Mail_smtp ()
	Destructor implementation to ensure that we disconnect from any potentially-alive persistent SMTP connections.
	send ($recipients, $headers, $body)
	Implements Mail::send() function using SMTP.
&	getSMTPObject ()
	Connect to the SMTP server by instantiating a Net_SMTP object.
	addServiceExtensionParameter ($keyword, $value=null)
	Add parameter associated with a SMTP service extension.
	disconnect ()
	Disconnect and destroy the current SMTP connection.
	_error ($text, &$error)
	Build a standardized string describing the current SMTP error.
Public Member Functions inherited from Mail
&	factory ($driver, $params=array())
	Provides an interface for generating Mail:: objects of various types.
	_sanitizeHeaders (&$headers)
	Sanitize an array of mail headers by removing any additional header strings present in a legitimate header's value.
	prepareHeaders ($headers)
	Take an array of mail headers and return a string containing text usable in sending a message.
	parseRecipients ($recipients)
	Take a set of recipients and parse them, returning an array of bare addresses (forward paths) that can be passed to sendmail or an smtp server with the rcpt to: command.

Data Fields
	$_smtp = null
	$_extparams = array()
	$host = 'localhost'
	$port = 25
	$auth = false
	$username = ''
	$password = ''
	$localhost = 'localhost'
	$timeout = null
	$debug = false
	Turn on Net_SMTP debugging?
	$persist = false
	$pipelining
Data Fields inherited from Mail
	$sep = "\r\n"

Detailed Description

Definition at line 74 of file smtp.php.

Member Function Documentation

Mail_smtp::_error	(		$text,
		&	$error
	)

Build a standardized string describing the current SMTP error.

Parameters

string	$text	Custom string describing the error context.
object	$error	Reference to the current PEAR_Error object.

Returns

string A string describing the current SMTP error.

Since

1.1.7 private

Definition at line 433 of file smtp.php.

Referenced by getSMTPObject(), and send().

    {
        /* Split the SMTP response into a code and a response string. */
        list($code, $response) = $this->_smtp->getResponse();

        /* Build our standardized error string. */
        return $text
            . ' [SMTP: ' . $error->getMessage()
            . " (code: $code, response: $response)]";
    }

Here is the caller graph for this function:

Mail_smtp::_Mail_smtp

(

)

Destructor implementation to ensure that we disconnect from any potentially-alive persistent SMTP connections.

Definition at line 216 of file smtp.php.

References disconnect().

    {
        $this->disconnect();
    }

Here is the call graph for this function:

Mail_smtp::addServiceExtensionParameter	(		$keyword,
			$value = null
	)

Add parameter associated with a SMTP service extension.

Parameters

string	Extension keyword.
string	Any value the keyword needs.

Since

1.2.0 public

Definition at line 398 of file smtp.php.

Referenced by Mail_smtp().

    {
        $this->_extparams[$keyword] = $value;
    }

Here is the caller graph for this function:

Mail_smtp::disconnect

(

)

Disconnect and destroy the current SMTP connection.

Returns

boolean True if the SMTP connection no longer exists.

Since

1.1.9 public

Definition at line 411 of file smtp.php.

Referenced by _Mail_smtp(), and send().

    {
        /* If we have an SMTP object, disconnect and destroy it. */
        if (is_object($this->_smtp) && $this->_smtp->disconnect()) {
            $this->_smtp = null;
        }

        /* We are disconnected if we no longer have an SMTP object. */
        return ($this->_smtp === null);
    }

Here is the caller graph for this function:

& Mail_smtp::getSMTPObject

(

)

Connect to the SMTP server by instantiating a Net_SMTP object.

Returns

mixed Returns a reference to the Net_SMTP object on success, or a PEAR_Error containing a descriptive error message on failure.

Since

1.2.0 public

Definition at line 342 of file smtp.php.

References $_smtp, $res, _error(), PEAR\isError(), PEAR_MAIL_SMTP_ERROR_AUTH, PEAR_MAIL_SMTP_ERROR_CONNECT, PEAR_MAIL_SMTP_ERROR_CREATE, and PEAR\raiseError().

Referenced by send().

    {
        if (is_object($this->_smtp) !== false) {
            return $this->_smtp;
        }

        include_once 'Net/SMTP.php';
        $this->_smtp = &new Net_SMTP($this->host,
                                     $this->port,
                                     $this->localhost);

        /* If we still don't have an SMTP object at this point, fail. */
        if (is_object($this->_smtp) === false) {
            return PEAR::raiseError('Failed to create a Net_SMTP object',
                                    PEAR_MAIL_SMTP_ERROR_CREATE);
        }

        /* Configure the SMTP connection. */
        if ($this->debug) {
            $this->_smtp->setDebug(true);
        }

        /* Attempt to connect to the configured SMTP server. */
        if (PEAR::isError($res = $this->_smtp->connect($this->timeout))) {
            $error = $this->_error('Failed to connect to ' .
                                   $this->host . ':' . $this->port,
                                   $res);
            return PEAR::raiseError($error, PEAR_MAIL_SMTP_ERROR_CONNECT);
        }

        /* Attempt to authenticate if authentication has been enabled. */
        if ($this->auth) {
            $method = is_string($this->auth) ? $this->auth : '';

            if (PEAR::isError($res = $this->_smtp->auth($this->username,
                                                        $this->password,
                                                        $method))) {
                $error = $this->_error("$method authentication failure",
                                       $res);
                $this->_smtp->rset();
                return PEAR::raiseError($error, PEAR_MAIL_SMTP_ERROR_AUTH);
            }
        }

        return $this->_smtp;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

Mail_smtp::Mail_smtp

(

$params

)

Constructor.

Instantiates a new Mail_smtp:: object based on the parameters passed in. It looks for the following parameters: host The server to connect to. Defaults to localhost. port The port to connect to. Defaults to 25. auth SMTP authentication. Defaults to none. username The username to use for SMTP auth. No default. password The password to use for SMTP auth. No default. localhost The local hostname / domain. Defaults to localhost. timeout The SMTP connection timeout. Defaults to none. verp Whether to use VERP or not. Defaults to false. DEPRECATED as of 1.2.0 (use setMailParams()). debug Activate SMTP debug mode? Defaults to false. persist Should the SMTP connection persist? pipelining Use SMTP command pipelining

If a parameter is present in the $params array, it replaces the default.

Parameters

array

Hash containing any parameters different from the defaults. public

Definition at line 191 of file smtp.php.

References addServiceExtensionParameter().

    {
        if (isset($params['host'])) $this->host = $params['host'];
        if (isset($params['port'])) $this->port = $params['port'];
        if (isset($params['auth'])) $this->auth = $params['auth'];
        if (isset($params['username'])) $this->username = $params['username'];
        if (isset($params['password'])) $this->password = $params['password'];
        if (isset($params['localhost'])) $this->localhost = $params['localhost'];
        if (isset($params['timeout'])) $this->timeout = $params['timeout'];
        if (isset($params['debug'])) $this->debug = (bool)$params['debug'];
        if (isset($params['persist'])) $this->persist = (bool)$params['persist'];
        if (isset($params['pipelining'])) $this->pipelining = (bool)$params['pipelining'];

        // Deprecated options
        if (isset($params['verp'])) {
            $this->addServiceExtensionParameter('XVERP', is_bool($params['verp']) ? null : $params['verp']);
        }

        register_shutdown_function(array(&$this, '_Mail_smtp'));
    }

Here is the call graph for this function:

Mail_smtp::send	(		$recipients,
			$headers,
			$body
	)

Implements Mail::send() function using SMTP.

Parameters

mixed	$recipients	Either a comma-seperated list of recipients (RFC822 compliant), or an array of recipients, each RFC822 valid. This may contain recipients not specified in the headers, for Bcc:, resending messages, etc.
array	$headers	The array of headers to send with the mail, in an associative array, where the array key is the header name (e.g., 'Subject'), and the array value is the header value (e.g., 'test'). The header produced from those values would be 'Subject: test'.
string	$body	The full text of the message body, including any MIME parts, etc.

Returns

mixed Returns true on success, or a PEAR_Error containing a descriptive error message on failure. public

Reimplemented from Mail.

Definition at line 245 of file smtp.php.

References $res, $result, _error(), Mail\_sanitizeHeaders(), disconnect(), getSMTPObject(), PEAR\isError(), Mail\parseRecipients(), PEAR_MAIL_SMTP_ERROR_DATA, PEAR_MAIL_SMTP_ERROR_FROM, PEAR_MAIL_SMTP_ERROR_RECIPIENT, PEAR_MAIL_SMTP_ERROR_SENDER, Mail\prepareHeaders(), and PEAR\raiseError().

    {
        /* If we don't already have an SMTP object, create one. */
        $result = &$this->getSMTPObject();
        if (PEAR::isError($result)) {
            return $result;
        }

        if (!is_array($headers)) {
            return PEAR::raiseError('$headers must be an array');
        }

        $this->_sanitizeHeaders($headers);

        $headerElements = $this->prepareHeaders($headers);
        if (is_a($headerElements, 'PEAR_Error')) {
            $this->_smtp->rset();
            return $headerElements;
        }
        list($from, $textHeaders) = $headerElements;

        /* Since few MTAs are going to allow this header to be forged
         * unless it's in the MAIL FROM: exchange, we'll use
         * Return-Path instead of From: if it's set. */
        if (!empty($headers['Return-Path'])) {
            $from = $headers['Return-Path'];
        }

        if (!isset($from)) {
            $this->_smtp->rset();
            return PEAR::raiseError('No From: address has been provided',
                                    PEAR_MAIL_SMTP_ERROR_FROM);
        }

        $params = null;
        if (!empty($this->_extparams)) {
            foreach ($this->_extparams as $key => $val) {
                $params .= ' ' . $key . (is_null($val) ? '' : '=' . $val);
            }
        }
        if (PEAR::isError($res = $this->_smtp->mailFrom($from, ltrim($params)))) {
            $error = $this->_error("Failed to set sender: $from", $res);
            $this->_smtp->rset();
            return PEAR::raiseError($error, PEAR_MAIL_SMTP_ERROR_SENDER);
        }

        $recipients = $this->parseRecipients($recipients);
        if (is_a($recipients, 'PEAR_Error')) {
            $this->_smtp->rset();
            return $recipients;
        }

        foreach ($recipients as $recipient) {
            $res = $this->_smtp->rcptTo($recipient);
            if (is_a($res, 'PEAR_Error')) {
                $error = $this->_error("Failed to add recipient: $recipient", $res);
                $this->_smtp->rset();
                return PEAR::raiseError($error, PEAR_MAIL_SMTP_ERROR_RECIPIENT);
            }
        }

        /* Send the message's headers and the body as SMTP data. */
        $res = $this->_smtp->data($textHeaders . "\r\n\r\n" . $body);
                list(,$args) = $this->_smtp->getResponse();

                if (preg_match("/Ok: queued as (.*)/", $args, $queued)) {
                        $this->queued_as = $queued[1];
                }

                /* we need the greeting; from it we can extract the authorative name of the mail server we've really connected to.
                 * ideal if we're connecting to a round-robin of relay servers and need to track which exact one took the email */
                $this->greeting = $this->_smtp->getGreeting();

        if (is_a($res, 'PEAR_Error')) {
            $error = $this->_error('Failed to send data', $res);
            $this->_smtp->rset();
            return PEAR::raiseError($error, PEAR_MAIL_SMTP_ERROR_DATA);
        }

        /* If persistent connections are disabled, destroy our SMTP object. */
        if ($this->persist === false) {
            $this->disconnect();
        }

        return true;
    }

Here is the call graph for this function:

Field Documentation

Mail_smtp::$_extparams = array()

Definition at line 89 of file smtp.php.

Mail_smtp::$_smtp = null

Definition at line 82 of file smtp.php.

Referenced by getSMTPObject().

Mail_smtp::$auth = false

Definition at line 114 of file smtp.php.

boolean Mail_smtp::$debug = false

Turn on Net_SMTP debugging?

Definition at line 148 of file smtp.php.

Mail_smtp::$host = 'localhost'

Definition at line 95 of file smtp.php.

Mail_smtp::$localhost = 'localhost'

Definition at line 134 of file smtp.php.

Mail_smtp::$password = ''

Definition at line 126 of file smtp.php.

Mail_smtp::$persist = false

Definition at line 156 of file smtp.php.

Mail_smtp::$pipelining

Definition at line 164 of file smtp.php.

Mail_smtp::$port = 25

Definition at line 101 of file smtp.php.

Mail_smtp::$timeout = null

Definition at line 141 of file smtp.php.

Mail_smtp::$username = ''

Definition at line 120 of file smtp.php.

---

The documentation for this class was generated from the following file:

• Services/PEAR/lib/Mail/smtp.php