Zeta Components - high quality PHP components

Zeta Components Manual :: Docs For Class ezcMailPop3Transport

Mail::ezcMailPop3Transport

Class ezcMailPop3Transport

The class ezcMailPop3Transport implements functionality for handling POP3 mail servers.

The implementation supports most of the commands specified in:

The POP3 server can be in different states. Most POP3 commands require that a connection is established and a user is authenticated.

The POP3 transport class allows developers to interface with a POP3 server.

Basic commands:

Work with message numbers: Work with ezcMailPop3Set sets (parseable with ezcMailParser): Miscellaneous commands:
  • get the status of messages on the server (status())
  • issue a NOOP command to keep the connection alive (noop())
The usual operation with a POP3 server is illustrated by this example:
  1.  // create a new POP3 transport object by specifying the server name, optional
  2.  // port and optional SSL mode
  3.  $options = new ezcMailPop3TransportOptions();
  4.  $options->ssl = true;
  5.  
  6.  $pop3 = new ezcMailPop3Transport( 'pop3.example.com', null, $options );
  7.  
  8.  // Authenticate to the POP3 server
  9.  $pop3->authenticate( 'username', 'password' );
  10.  
  11.  // issue commands to the POP3 server
  12.  // for example get the headers of the first message, which can be
  13.  // parsed with ezcMailVariableSet and ezcMailParser
  14.  $headers = $pop3->top( 1 );
  15.  
  16.  // see the above list of commands or consult the online documentation for
  17.  // the full list of commands you can issue to an POP3 server and examples
  18.  
  19.  // disconnect from the POP3 server
  20.  $pop3->disconnect();

See ezcMailPop3TransportOptions for options you can specify for POP3.

Source for this file: /Mail/src/transports/pop3/pop3_transport.php

Version:   //autogen//
Todo:   ignore messages of a certain size?
Todo:   // support for signing?

Constants

AUTH_APOP = 2 APOP authorization.
AUTH_PLAIN_TEXT = 1 Plain text authorization.

Properties

ezcMailPop3TransportOptions read/write $options
Holds the options you can set to the POP3 transport.

Member Variables

protected ezcMailTransportConnection $connection = null
The connection to the POP3 server.
protected string $greeting = null
Holds the initial greeting from the POP3 server when connecting.
protected mixed $state = self::STATE_NOT_CONNECTED
Holds the connection state.

$var int STATE_NOT_CONNECTED, STATE_AUTHORIZATION, STATE_TRANSACTION or STATE_UPDATE.

Method Summary

public ezcMailPop3Transport __construct( $server , [ $port = null] , [ $options = array()] )
Creates a new POP3 transport and connects to the $server at $port.
public void __destruct( )
Destructs the POP3 transport object.
public void authenticate( $user , $password , [ $method = null] )
Authenticates the user to the POP3 server with $user and $password.
public void delete( $msgNum )
Deletes the message with the message number $msgNum from the server.
public void disconnect( )
Disconnects the transport from the POP3 server.
public ezcMailParserSet fetchAll( [ $deleteFromServer = false] )
Returns an ezcMailPop3Set with all the messages on the server.
public ezcMailPop3Set fetchByMessageNr( $number , [ $deleteFromServer = false] )
Returns an ezcMailPop3Set containing only the $number -th message from the server.
public ezcMailPop3Set fetchFromOffset( $offset , [ $count = 0] , [ $deleteFromServer = false] )
Returns an ezcMailPop3Set with $count messages starting from $offset from the server.
protected bool isPositiveResponse( $line )
Returns true if the response from the server is a positive one.
public array(int) listMessages( )
Returns an array of the message numbers on the server and the size of the messages in bytes.
public array(string) listUniqueIdentifiers( [ $msgNum = null] )
Returns the unique identifiers for messages on the POP3 server.
public void noop( )
Sends a NOOP command to the server, use it to keep the connection alive.
public void status( &$numMessages , &$sizeMessages )
Returns information about the messages on the server.
public string top( $msgNum , [ $numLines = 0] )
Returns the headers and the $numLines first lines of the body of the mail with the message number $msgNum.

Methods

__construct

ezcMailPop3Transport __construct( string $server , [int $port = null] , [ezcMailPop3TransportOptions|array(string=>mixed) $options = array()] )

Creates a new POP3 transport and connects to the $server at $port.

You can specify the $port if the POP3 server is not on the default port 995 (for SSL connections) or 110 (for plain connections). Use the $options parameter to specify an SSL connection.

For options you can specify for POP3 see ezcMailPop3TransportOptions.

Example of creating a POP3 transport:

  1.  // replace with your POP3 server address
  2.  $pop3 = new ezcMailPop3Transport( 'pop3.example.com' );
  3.  
  4.  // if you want to use SSL:
  5.  $options = new ezcMailPop3TransportOptions();
  6.  $options->ssl = true;
  7.  
  8.  $pop3 = new ezcMailPop3Transport( 'pop3.example.com', null, $options );
Parameters:
Name Type Description
$server string
$port int
$options ezcMailPop3TransportOptions|array(string=>mixed)
Exceptions:
Type Description
ezcMailTransportException if it was not possible to connect to the server
ezcBaseValueException if $options contains a property with a value not allowed
ezcBaseExtensionNotFoundException if trying to use SSL and the extension openssl is not installed
ezcBasePropertyNotFoundException if $options contains a property not defined

__destruct

void __destruct( )

Destructs the POP3 transport object.

If there is an open connection to the POP3 server it is closed.

authenticate

void authenticate( string $user , string $password , [int $method = null] )

Authenticates the user to the POP3 server with $user and $password.

You can choose the authentication method with the $method parameter. The default is to use plaintext username and password (specified in the ezcMailPop3TransportOptions class).

This method should be called directly after the construction of this object.

Example:

  1.  // replace with your POP3 server address
  2.  $pop3 = new ezcMailPop3Transport( 'pop3.example.com' );
  3.  
  4.  // replace the values with your username and password for the POP3 server
  5.  $pop3->authenticate( 'username', 'password' );
Parameters:
Name Type Description
$user string
$password string
$method int
Exceptions:
Type Description
ezcMailTransportException if there is no connection to the server or if already authenticated or if the authentication method is not accepted by the server or if the provided username/password combination did not work

delete

void delete( int $msgNum )

Deletes the message with the message number $msgNum from the server.

The message number must be a valid identifier fetched with (example) listMessages().

Any future reference to the message-number associated with the message in a command generates an error.

Before calling this method, a connection to the POP3 server must be established and a user must be authenticated successfully.

Parameters:
Name Type Description
$msgNum int
Exceptions:
Type Description
ezcMailTransportException if there was no connection to the server or if not authenticated or if the server sent a negative response

disconnect

void disconnect( )

Disconnects the transport from the POP3 server.

fetchAll

ezcMailParserSet fetchAll( [bool $deleteFromServer = false] )

Returns an ezcMailPop3Set with all the messages on the server.

If $deleteFromServer is set to true the mail will be removed from the server after retrieval. If not it will be left.

Before calling this method, a connection to the POP3 server must be established and a user must be authenticated successfully.

Example:

  1.  $pop3 = new ezcMailPop3Transport( 'pop3.example.com' );
  2.  $pop3->authenticate( 'username', 'password' );
  3.  
  4.  $set = $pop3->fetchAll();
  5.  
  6.  // parse $set with ezcMailParser
  7.  $parser = new ezcMailParser();
  8.  $mails = $parser->parseMail( $set );
  9.  foreach ( $mails as $mail )
  10.  {
  11.      // process $mail which is an ezcMail object
  12.  }
Parameters:
Name Type Description
$deleteFromServer bool
Exceptions:
Type Description
ezcMailTransportException if there was no connection to the server or if not authenticated or if the server sent a negative response

fetchByMessageNr

ezcMailPop3Set fetchByMessageNr( int $number , [bool $deleteFromServer = false] )

Returns an ezcMailPop3Set containing only the $number -th message from the server.

If $deleteFromServer is set to true the mail will be removed from the server after retrieval. If not it will be left.

Note: for POP3 the first message is 1 (so for $number = 0 the exception will be thrown).

Before calling this method, a connection to the POP3 server must be established and a user must be authenticated successfully.

Example:

  1.  $pop3 = new ezcMailPop3Transport( 'pop3.example.com' );
  2.  $pop3->authenticate( 'username', 'password' );
  3.  
  4.  $set = $pop3->fetchByMessageNr( 1 );
  5.  
  6.  // $set can be parsed with ezcMailParser
Parameters:
Name Type Description
$number int
$deleteFromServer bool
Exceptions:
Type Description
ezcMailNoSuchMessageException if the message $number is out of range
ezcMailTransportException if there was no connection to the server or if not authenticated or if the server sent a negative response

fetchFromOffset

ezcMailPop3Set fetchFromOffset( int $offset , [int $count = 0] , [bool $deleteFromServer = false] )

Returns an ezcMailPop3Set with $count messages starting from $offset from the server.

Fetches $count messages starting from the $offset and returns them as a ezcMailPop3Set. If $count is not specified or if it is 0, it fetches all messages starting from the $offset.

Before calling this method, a connection to the POP3 server must be established and a user must be authenticated successfully.

Example:

  1.  $pop3 = new ezcMailPop3Transport( 'pop3.example.com' );
  2.  $pop3->authenticate( 'username', 'password' );
  3.  
  4.  $set = $pop3->fetchFromOffset( 1, 10 );
  5.  
  6.  // $set can be parsed with ezcMailParser
Parameters:
Name Type Description
$offset int
$count int
$deleteFromServer bool
Exceptions:
Type Description
ezcMailTransportException if there was no connection to the server or if not authenticated or if the server sent a negative response
ezcMailInvalidLimitException if $count is negative
ezcMailOffsetOutOfRangeException if $offset is outside of the existing range of messages

isPositiveResponse

bool isPositiveResponse( string $line )

Returns true if the response from the server is a positive one.

Parameters:
Name Type Description
$line string

listMessages

array(int) listMessages( )

Returns an array of the message numbers on the server and the size of the messages in bytes.

The format of the returned array is:

  1.    array( message_id => message_size );

Example:

  1.    array( 2 => 1700, 5 => 1450, 6 => 21043 );

Before calling this method, a connection to the POP3 server must be established and a user must be authenticated successfully.

Exceptions:
Type Description
ezcMailTransportException if there was no connection to the server or if not authenticated or if the server sent a negative response

listUniqueIdentifiers

array(string) listUniqueIdentifiers( [int $msgNum = null] )

Returns the unique identifiers for messages on the POP3 server.

You can fetch the unique identifier for a specific message by providing the $msgNum parameter.

The unique identifier can be used to recognize mail from servers between requests. In contrast to the message numbers the unique numbers assigned to an email usually never changes.

Note: POP3 servers are not required to support this command and it may fail.

The format of the returned array is:

  1.    array( message_num => unique_id );

Before calling this method, a connection to the POP3 server must be established and a user must be authenticated successfully.

Example:

  1.    array( 1 => '000001fc4420e93a', 2 => '000001fd4420e93a' );
Parameters:
Name Type Description
$msgNum int
Exceptions:
Type Description
ezcMailTransportException if there was no connection to the server or if not authenticated or if the server sent a negative response

noop

void noop( )

Sends a NOOP command to the server, use it to keep the connection alive.

Before calling this method, a connection to the POP3 server must be established and a user must be authenticated successfully.

Exceptions:
Type Description
ezcMailTransportException if there was no connection to the server or if not authenticated or if the server sent a negative response

status

void status( int &$numMessages , int &$sizeMessages )

Returns information about the messages on the server.

The information returned through the parameters is:

  • $numMessages = number of messages
  • $sizeMessages = sum of the messages sizes
Before calling this method, a connection to the POP3 server must be established and a user must be authenticated successfully.

Example of returning the status of messages on the server:

  1.  $pop3 = new ezcMailPop3Transport( 'pop3.example.com' );
  2.  $pop3->authenticate( 'username', 'password' );
  3.  
  4.  $pop3->status( $numMessages, $sizeMessages );

After running the above code, $numMessages and $sizeMessages will be populated with values.

Parameters:
Name Type Description
&$numMessages int
&$sizeMessages int
Exceptions:
Type Description
ezcMailTransportException if there was no connection to the server or if not authenticated or if the server sent a negative response

top

string top( int $msgNum , [int $numLines = 0] )

Returns the headers and the $numLines first lines of the body of the mail with the message number $msgNum.

If the command failed or if it was not supported by the server an empty string is returned.

Note: POP3 servers are not required to support this command and it may fail.

Before calling this method, a connection to the POP3 server must be established and a user must be authenticated successfully.

Example of listing the mail headers of all the messages from the server:

  1.  $pop3 = new ezcMailPop3Transport( 'pop3.example.com' );
  2.  $pop3->authenticate( 'username', 'password' );
  3.  
  4.  $parser = new ezcMailParser();
  5.  $messages = $pop3->listMessages();
  6.  foreach ( $messages as $messageNr => $size )
  7.  {
  8.      $set = new ezcMailVariableSet( $pop3->top( $messageNr ) );
  9.      $mail = $parser->parseMail( $set );
  10.      $mail = $mail[0];
  11.      echo "From: {$mail->from}, Subject: {$mail->subject}, Size: {$size}\n";
  12.  }
Parameters:
Name Type Description
$msgNum int
$numLines int
Exceptions:
Type Description
ezcMailTransportException if there was no connection to the server or if not authenticated or if the server sent a negative response
Documentation generated by phpDocumentor 1.4.3