Path

ez components / documentation / api reference / 2009.1rc1 / mail


eZ Components 2009.1rc1

Mail: ezcMailSmtpTransport

[ Tutorial ] [ Display example ] [ Mail listing example ] [ Rfcs ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcMailSmtpTransport

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

Implemented Interfaces

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->addTonew 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.

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

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, $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 static array(string) getSupportedAuthMethods( )
Returns an array with the authentication methods supported by the SMTP transport class (not by the SMTP 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

auth

bool auth( $method )
Calls the appropiate authentication method based on $method.

Parameters

Name Type Description
$method  

Throws

ClassDescription
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.

Throws

ClassDescription
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.

Throws

ClassDescription
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.

Throws

ClassDescription
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.

Throws

ClassDescription
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.

Throws

ClassDescription
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)  

Throws

ClassDescription
ezcBasePropertyNotFoundException if $options contains a property not defined
ezcBaseValueException if $options contains a property with a value not allowed

__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.

Throws

ClassDescription
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  

Throws

ClassDescription
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  

Throws

ClassDescription
ezcMailTransportSmtpException if there is no valid connection or if the RCPT TO command failed

composeSmtpMailAddress

void composeSmtpMailAddress( $email, 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
$email  

connect

void connect( )
Creates a connection to the SMTP server and initiates the login procedure.

Throws

ClassDescription
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.

Throws

ClassDescription
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.

Throws

ClassDescription
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  

Throws

ClassDescription
ezcMailTransportSmtpException if it could not fetch data from the stream

getSupportedAuthMethods

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.

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.

Throws

ClassDescription
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  

Throws

ClassDescription
ezcMailTransportException if the mail could not be sent
ezcBaseFeatureNotFoundException if trying to use SSL and the openssl extension is not installed

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  

Throws

ClassDescription
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)  

Last updated: Mon, 22 Jun 2009