Zeta Components - high quality PHP components

Zeta Components Manual :: Docs For Class ezcMailSmtpTransport

Mail::ezcMailSmtpTransport

Class ezcMailSmtpTransport

This class implements the Simple Mail Transfer Protocol (SMTP) with authentication support.

The implementation supports most of the commands specified in:

By default, the SMTP transport tries to login anonymously to the SMTP server (if an empty username and password have been provided), or to authenticate with the strongest method supported by the server (if username and password have been provided). The default behaviour can be changed with the option preferredAuthMethod (see ezcMailSmtpTransportOptions).

If the preferred method is specified via options, only that authentication method will be attempted on the SMTP server. If it fails, an exception will be thrown.

Supported authentication methods (from strongest to weakest):

  • DIGEST-MD5
  • CRAM-MD5
  • NTLM (requires the PHP mcrypt extension)
  • LOGIN
  • PLAIN
Not all SMTP servers support these methods, and some SMTP servers don't support authentication at all.

Example send mail:

  1.  $mail = new ezcMailComposer();
  2.  
  3.  $mail->from = new ezcMailAddress( 'sender@example.com', 'Adrian Ripburger' );
  4.  $mail->addTo( new ezcMailAddress( 'receiver@example.com', 'Maureen Corley' ) );
  5.  $mail->subject = "This is the subject of the example mail";
  6.  $mail->plainText = "This is the body of the example mail.";
  7.  $mail->build();
  8.  
  9.  // Create a new SMTP transport object with an SSLv3 connection.
  10.  // The port will be 465 by default, use the 4th argument to change it.
  11.  // Username and password (2nd and 3rd arguments) are left blank, which means
  12.  // the mail host does not need authentication.
  13.  // The 5th parameter is the optional $options object.
  14.  $options = new ezcMailSmtpTransportOptions();
  15.  $options->connectionType = ezcMailSmtpTransport::CONNECTION_SSLV3;
  16.  
  17.  $transport = new ezcMailSmtpTransport( 'mailhost.example.com', '', '', null, $options );
  18.  
  19.  // Use the SMTP transport to send the created mail object
  20.  $transport->send( $mail );

Example require NTLM authentication:

  1.  // Create an SMTP transport and demand NTLM authentication.
  2.  // Username and password must be specified, otherwise no authentication
  3.  // will be attempted.
  4.  // If NTLM authentication fails, an exception will be thrown.
  5.  $options = new ezcMailSmtpTransportOptions();
  6.  $options->preferredAuthMethod = ezcMailSmtpTransport::AUTH_NTLM;
  7.  
  8.  $transport = new ezcMailSmtpTransport( 'mailhost.example.com', 'username', 'password', null, $options );
  9.  
  10.  // The option can also be specified via the option property:
  11.  $transport->options->preferredAuthMethod = ezcMailSmtpTransport::AUTH_NTLM;

See ezcMailSmtpTransportOptions for options you can specify for SMTP.

Source for this file: /Mail/src/transports/smtp/smtp_transport.php

Implements interfaces:

Version:   //autogen//

Constants

AUTH_AUTO = null No authentication method. Specifies that the transport should try to authenticate using the methods supported by the SMTP server in their decreasing strength order. If one method fails an exception will be thrown.
AUTH_CRAM_MD5 = 'CRAM-MD5' Authenticate with 'AUTH CRAM-MD5'.
AUTH_DIGEST_MD5 = 'DIGEST-MD5' Authenticate with 'AUTH DIGEST-MD5'.
AUTH_LOGIN = 'LOGIN' Authenticate with 'AUTH LOGIN'.
AUTH_NTLM = 'NTLM' Authenticate with 'AUTH NTLM'.
AUTH_PLAIN = 'PLAIN' Authenticate with 'AUTH PLAIN'.
CONNECTION_PLAIN = 'tcp' Plain connection.
CONNECTION_SSL = 'ssl' SSL connection.
CONNECTION_SSLV2 = 'sslv2' SSLv2 connection.
CONNECTION_SSLV3 = 'sslv3' SSLv3 connection.
CONNECTION_TLS = 'tls' TLS connection.

Properties

ezcMailSmtpTransportOptions read/write $options
Holds the options you can set to the SMTP transport.
string read/write $password
The password used for authentication.
string read/write $senderHost
The hostname of the computer that sends the mail. The default is 'localhost'.
string read/write $serverHost
The SMTP server host to connect to.
int read/write $serverPort
The port of the SMTP server. Defaults to 25.
int read/write $timeout
The timeout value of the connection in seconds. The default is 5 seconds. When setting/getting this option, the timeout option from $this->options ezcMailTransportOptions will be set instead.
string read/write $username
The username used for authentication. The default is blank which means no authentication.

Member Variables

protected resource $connection
The connection to the SMTP server.
protected bool $doAuthenticate
True if authentication should be performed; otherwise false.

This variable is set to true if a username is provided for login.

protected bool $keepConnection = false
Holds if the connection should be kept open after sending a mail.
protected ezcMailSmtpTransportOptions $options
Holds the options of this class.
protected array(string=>mixed) $properties = array()
Holds the properties of this class.
protected mixed $status
Holds the connection status.

$var int STATUS_NOT_CONNECTED, STATUS_CONNECTED or STATUS_AUTHENTICATED.

Method Summary

public static array(string) getSupportedAuthMethods( )
Returns an array with the authentication methods supported by the SMTP transport class (not by the SMTP server!).
protected bool auth( $method )
Calls the appropiate authentication method based on $method.
protected bool authCramMd5( )
Tries to login to the SMTP server with 'AUTH CRAM-MD5' and returns true if successful.
protected bool authDigestMd5( )
Tries to login to the SMTP server with 'AUTH DIGEST-MD5' and returns true if successful.
protected bool authLogin( )
Tries to login to the SMTP server with 'AUTH LOGIN' and returns true if successful.
protected bool authNtlm( )
Tries to login to the SMTP server with 'AUTH NTLM' and returns true if successful.
protected string authNtlmMessageType1( $workstation , $domain )
Generates an NTLM type 1 message.
protected string authNtlmMessageType3( $challenge , $user , $password , $workstation , $domain )
Generates an NTLM type 3 message from the $challenge sent by the SMTP server in an NTLM type 2 message.
protected string authNtlmResponse( $challenge , $password )
Calculates an NTLM response to be used in the creation of the NTLM type 3 message.
protected string authNtlmSecurityBuffer( $text , $offset )
Creates an NTLM security buffer information string.
protected bool authPlain( )
Tries to login to the SMTP server with 'AUTH PLAIN' and returns true if successful.
public ezcMailSmtpTransport __construct( $host , [ $user = ''] , [ $password = ''] , [ $port = null] , [ $options = array()] )
Constructs a new ezcMailSmtpTransport.
public void __destruct( )
Destructs this object.
protected void cmdData( )
Sends the DATA command to the SMTP server.
protected void cmdMail( $from )
Sends the MAIL FROM command, with the sender's mail address $from.
protected void cmdRcpt( $email )
Sends the 'RCTP TO' to the server with the address $email.
protected void composeSmtpMailAddress( $email )
Returns the $email enclosed within '< >'.
protected void connect( )
Creates a connection to the SMTP server and initiates the login procedure.
public void disconnect( )
Sends the QUIT command to the server and breaks the connection.
protected string generateNonce( [ $length = 32] )
Generates an alpha-numeric random string with the specified $length.
protected string getData( )
Returns data received from the connection stream.
protected string getReplyCode( &$line )
Returns the reply code of the last message from the server.
public void keepConnection( )
Sets if the connection should be kept open after sending an email.
protected void login( )
Performs the initial handshake with the SMTP server and authenticates the user, if login data is provided to the constructor.
public void send( $mail )
Sends the ezcMail $mail using the SMTP protocol.
protected void sendData( $data )
Sends $data to the SMTP server through the connection.
protected array(string) sortAuthMethods( $methods )
Sorts the specified array of AUTH methods $methods by strength, so higher strength methods will be used first.

Methods

getSupportedAuthMethods

static array(string) getSupportedAuthMethods( )

Returns an array with the authentication methods supported by the SMTP transport class (not by the SMTP server!).

The returned array has the methods sorted by their relative strengths, so stronger methods are first in the array.

auth

bool auth( $method )

Calls the appropiate authentication method based on $method.

Parameters:
Name Type Description
$method
Exceptions:
Type Description
ezcMailTransportSmtpException if $method is not supported by the transport class

authCramMd5

bool authCramMd5( )

Tries to login to the SMTP server with 'AUTH CRAM-MD5' and returns true if successful.

Exceptions:
Type Description
ezcMailTransportSmtpException if the SMTP server returned an error

authDigestMd5

bool authDigestMd5( )

Tries to login to the SMTP server with 'AUTH DIGEST-MD5' and returns true if successful.

Exceptions:
Type Description
ezcMailTransportSmtpException if the SMTP server returned an error

authLogin

bool authLogin( )

Tries to login to the SMTP server with 'AUTH LOGIN' and returns true if successful.

Exceptions:
Type Description
ezcMailTransportSmtpException if the SMTP server returned an error

authNtlm

bool authNtlm( )

Tries to login to the SMTP server with 'AUTH NTLM' and returns true if successful.

Exceptions:
Type Description
ezcMailTransportSmtpException if the SMTP server returned an error

authNtlmMessageType1

string authNtlmMessageType1( string $workstation , string $domain )

Generates an NTLM type 1 message.

Parameters:
Name Type Description
$workstation string
$domain string

authNtlmMessageType3

string authNtlmMessageType3( string $challenge , string $user , string $password , string $workstation , string $domain )

Generates an NTLM type 3 message from the $challenge sent by the SMTP server in an NTLM type 2 message.

Parameters:
Name Type Description
$challenge string
$user string
$password string
$workstation string
$domain string

authNtlmResponse

string authNtlmResponse( string $challenge , string $password )

Calculates an NTLM response to be used in the creation of the NTLM type 3 message.

Parameters:
Name Type Description
$challenge string
$password string

authNtlmSecurityBuffer

string authNtlmSecurityBuffer( string $text , int $offset )

Creates an NTLM security buffer information string.

The structure of the security buffer is:

  • a short containing the length of the buffer content in bytes (may be zero).
  • a short containing the allocated space for the buffer in bytes (greater than or equal to the length; typically the same as the length).
  • a long containing the offset to the start of the buffer in bytes (from the beginning of the NTLM message).
Example:
  • buffer content length: 1234 bytes (0xd204 in hexa)
  • allocated space: 1234 bytes( 0xd204 in hexa)
  • offset: 4321 bytes (0xe1100000 in hexa)
then the security buffer would be 0xd204d204e1100000 (in hexa).
Parameters:
Name Type Description
$text string
$offset int

authPlain

bool authPlain( )

Tries to login to the SMTP server with 'AUTH PLAIN' and returns true if successful.

Exceptions:
Type Description
ezcMailTransportSmtpException if the SMTP server returned an error

__construct

ezcMailSmtpTransport __construct( string $host , [string $user = ''] , [string $password = ''] , [int $port = null] , [ezcMailSmtpTransportOptions|array(string=>mixed) $options = array()] )

Constructs a new ezcMailSmtpTransport.

The constructor expects, at least, the hostname $host of the SMTP server.

The username $user will be used for authentication if provided. If it is left blank no authentication will be performed.

The password $password will be used for authentication if provided. Use this parameter always in combination with the $user parameter.

The value $port specifies on which port to connect to $host. By default it is 25 for plain connections and 465 for TLS/SSL/SSLv2/SSLv3.

Note: The ssl option from ezcMailTransportOptions doesn't apply to SMTP. If you want to connect to SMTP using TLS/SSL/SSLv2/SSLv3 use the connectionType option in ezcMailSmtpTransportOptions.

For options you can specify for SMTP see ezcMailSmtpTransportOptions.

Parameters:
Name Type Description
$host string
$user string
$password string
$port int
$options ezcMailSmtpTransportOptions|array(string=>mixed)
Exceptions:
Type Description
ezcBaseValueException if $options contains a property with a value not allowed
ezcBasePropertyNotFoundException if $options contains a property not defined

__destruct

void __destruct( )

Destructs this object.

Closes the connection if it is still open.

cmdData

void cmdData( )

Sends the DATA command to the SMTP server.

Exceptions:
Type Description
ezcMailTransportSmtpException if there is no valid connection or if the DATA command failed

cmdMail

void cmdMail( string $from )

Sends the MAIL FROM command, with the sender's mail address $from.

This method must be called once to tell the server the sender address.

The sender's mail address $from may be enclosed in angle brackets.

Parameters:
Name Type Description
$from string
Exceptions:
Type Description
ezcMailTransportSmtpException if there is no valid connection or if the MAIL FROM command failed

cmdRcpt

void cmdRcpt( string $email )

Sends the 'RCTP TO' to the server with the address $email.

This method must be called once for each recipient of the mail including cc and bcc recipients. The RCPT TO commands control where the mail is actually sent. It does not affect the headers of the email.

The recipient mail address $email may be enclosed in angle brackets.

Parameters:
Name Type Description
$email string
Exceptions:
Type Description
ezcMailTransportSmtpException if there is no valid connection or if the RCPT TO command failed

composeSmtpMailAddress

void composeSmtpMailAddress( string $email )

Returns the $email enclosed within '< >'.

If $email is already enclosed within '< >' it is returned unmodified.

Parameters:
Name Type Description
$email string $return string

connect

void connect( )

Creates a connection to the SMTP server and initiates the login procedure.

Exceptions:
Type Description
ezcMailTransportSmtpException if no connection could be made or if the login failed
ezcBaseExtensionNotFoundException if trying to use SSL and the openssl extension is not installed

disconnect

void disconnect( )

Sends the QUIT command to the server and breaks the connection.

Exceptions:
Type Description
ezcMailTransportSmtpException if the QUIT command failed

generateNonce

string generateNonce( [int $length = 32] )

Generates an alpha-numeric random string with the specified $length.

Used in the DIGEST-MD5 authentication method.

Parameters:
Name Type Description
$length int

getData

string getData( )

Returns data received from the connection stream.

Exceptions:
Type Description
ezcMailTransportSmtpException if there is no valid connection

getReplyCode

string getReplyCode( string &$line )

Returns the reply code of the last message from the server.

$line contains the complete data retrieved from the stream. This can be used to retrieve the error message in case of an error.

Parameters:
Name Type Description
&$line string
Exceptions:
Type Description
ezcMailTransportSmtpException if it could not fetch data from the stream

keepConnection

void keepConnection( )

Sets if the connection should be kept open after sending an email.

This method should be called prior to the first call to send().

Keeping the connection open is useful if you are sending a lot of mail. It removes the overhead of opening the connection after each mail is sent.

Use disconnect() to close the connection if you have requested to keep it open.

login

void login( )

Performs the initial handshake with the SMTP server and authenticates the user, if login data is provided to the constructor.

Exceptions:
Type Description
ezcMailTransportSmtpException if the HELO/EHLO command or authentication fails

send

void send( ezcMail $mail )

Sends the ezcMail $mail using the SMTP protocol.

If you want to send several emails use keepConnection() to leave the connection to the server open between each mail.

Parameters:
Name Type Description
$mail ezcMail
Exceptions:
Type Description
ezcBaseFeatureNotFoundException if trying to use SSL and the openssl extension is not installed
ezcMailTransportException if the mail could not be sent
Implementation of:
Method Description
ezcMailTransport::send() Sends the contents of $mail.

sendData

void sendData( string $data )

Sends $data to the SMTP server through the connection.

This method appends one line-break at the end of $data.

Parameters:
Name Type Description
$data string
Exceptions:
Type Description
ezcMailTransportSmtpException if there is no valid connection

sortAuthMethods

array(string) sortAuthMethods( $methods )

Sorts the specified array of AUTH methods $methods by strength, so higher strength methods will be used first.

For example, if the server supports:

  1.    $methods = array( 'PLAIN', 'LOGIN', 'CRAM-MD5' );

then this method will return:

  1.    $methods = array( 'CRAM-MD5', 'LOGIN', 'PLAIN' );
Parameters:
Name Type Description
$methods array(string)
Documentation generated by phpDocumentor 1.4.3