## Apache 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:

- RFC821 - SMTP
- RFC2554 - SMTP Authentication
- RFC2831 - DIGEST-MD5 Authentication
- RFC2195 - CRAM-MD5 Authentication
- NTLM Authentication

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 ();
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();
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;
17. $transport=new ezcMailSmtpTransport ('mailhost.example.com','','',null,$options);
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;
8. $transport=new ezcMailSmtpTransport ('mailhost.example.com','username','password',null,$options);
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:

- ezcMailTransport

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