eZ Components 2008.2.1

Getting Started

Components

Archive (1.3.2)
Authentication (1.2.3)
AuthenticationDatabaseTiein (1.1)
Base (1.6.1)
Cache (1.4)
Configuration (1.3.2)
ConsoleTools (1.5)
Database (1.4.3)
DatabaseSchema (1.4.2)
Debug (1.2)
Document (1.1.1)
EventLog (1.3)
EventLogDatabaseTiein (1.0.2)
Execution (1.1.1)
Feed (1.2.1)
File (1.2)
Graph (1.4.1)
GraphDatabaseTiein (1.0.1)
ImageAnalysis (1.1.3)
ImageConversion (1.3.5)
Mail (1.6.1)
MvcTools (1.0)
MvcMailTiein (1.0)
MvcTemplateTiein (1.0)
PersistentObject (1.5)
PersistentObjectDatabaseSchemaTiein (1.2.1)
PhpGenerator (1.0.4)
Search (1.0.3)
SignalSlot (1.1.1)
SystemInformation (1.0.7)
Template (1.3.2)
TemplateTranslationTiein (1.0)
Translation (1.2)
TranslationCacheTiein (1.1.2)
Tree (1.1.2)
TreeDatabaseTiein (1.1.1)
TreePersistentObjectTiein (1.0)
Url (1.2.2)
UserInput (1.4)
Webdav (1.1)
Workflow (1.3.1)
WorkflowDatabaseTiein (1.3)
WorkflowEventLogTiein (1.1)
WorkflowSignalSlotTiein (1.0)

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

ezcMailTransport

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.

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

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

Throws

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

Throws

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

Throws

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

Throws

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

Throws

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

Throws

Class	Description
`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

Class	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

Throws

Class	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

Throws

Class	Description
`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

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

Throws

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

Throws

Class	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

Throws

Class	Description
`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

Class	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

Throws

Class	Description
`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

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

Last updated: Mon, 09 Feb 2009

eZ Components

User menu

Path

eZ Components 2008.2.1

Getting Started

Components

Mail: ezcMailSmtpTransport

Class: ezcMailSmtpTransport

Implemented Interfaces

Constants

Properties

Member Variables

Method Summary

Methods

auth

Parameters

Throws

authCramMd5

Throws

authDigestMd5

Throws

authLogin

Throws

authNtlm

Throws

authNtlmMessageType1

Parameters

authNtlmMessageType3

Parameters

authNtlmResponse

Parameters

authNtlmSecurityBuffer

Parameters

authPlain

Throws

__construct

Parameters

Throws

__destruct

cmdData

Throws

cmdMail

Parameters

Throws

cmdRcpt

Parameters

Throws

composeSmtpMailAddress

Parameters

connect

Throws

disconnect

Throws

generateNonce

Parameters

getData

Throws

getReplyCode

Parameters

Throws

getSupportedAuthMethods

keepConnection

login

Throws

send

Parameters

Throws

sendData

Parameters

Throws

sortAuthMethods

Parameters