NAME

POP3 1.0 - An RFC 1939 compliant PHP wrapper to the POP3 protocol


SYNOPSIS

    include("class.POP3.php3");

    $pop3 = new POP3();

    if(!$pop3->connect("mail.yourserver.com",60))
    {
        echo "Ooops $pop3->ERROR <BR>\n";
            exit;
    }

    $login = 'cdi';
    $pass = 'secret';
    $Count = $pop3->login($login,$pass);
    if( (!$Count) or ($Count == -1) )
    {
        echo "<H1>Login Failed: $pop3->ERROR</H1>\n";
        exit;
    }

    // ONLY USE THIS IF YOUR PHP VERSION SUPPORTS IT!
    register_shutdown_function($pop3->quit());

    if ($Count < 1)
    {
        echo "Login OK: Inbox EMPTY<BR>\n";
    } else {
        echo "Login OK: Inbox contains [$Count] messages<BR>\n";
    }
    $MsgOne = $pop3->get(1);
    if( (!$MsgOne) or (gettype($MsgOne) != "array") )
    {
        echo "oops, $pop3->ERROR<BR>\n";
        exit;
    }
    while ( list ( $lineNum,$line ) = each ($MsgOne) )
    {
        echo "$line <BR>\n";
    }
    if(!$pop3->delete(1))
    {
        echo "oops $pop3->ERROR <BR>\n";
        $pop3->reset();
        exit;
    } else {
        echo "Message 1 Deleted <BR>\n";
    }
    exit;


DESCRIPTION

class.POP3.php3 is a wrapper to the POP3 protocol, as specified by RFC 1939. All mandatory POP3 commands are available, as are a few optional POP3 commands. Using this class you can construct your own POP3 based web mail program, check for new mail from the web, or even use POP3 to authenticate secured areas of your web site.


METHODS


POP3( $server = "", $timeout = "" )

The class is instantiated by a call to the POP3() or new POP3() method. This method does not require arguments, but will set the global MAILSERVER and global TIMEOUT vars to the specified values if they are submitted. See MAILSERVER and TIMEOUT in the VARIABLES section.


connect($server, $port = 110)

This method must be called before any POP3 command can be sent. This actually creates the socket connection to the specified server, using either a user supplied port number or the POP3 default port 110. Returns true or false. If the connection succeeds, it sets the global var FP to the file pointer returned by the fsocketopen() call.


user($user = "")

Sends the POP3 USER command to the server. The only allowable argument is the login id (mailbox name) of the user. Returns true on success, false on failure. Believe it or not, but the USER POP3 command is OPTIONAL per RFC 1939. If this is the case, the most probable login method is going to be APOP. Check with your server administrator to find out for sure.


pass($pass = "")

Sends the POP3 PASS command to the server. The only allowable argument is the password for the mailbox specified by USER. Returns false on failure, and returns the number of messages in the mailbox on success. If login is successful but a problem occurs when trying to get the number of messages, the method returns -1. Believe it or not, but PASS is OPTIONAL per RFC 1939 and may not be supported by your server. If this is the case, you're seriously screwed unless they support APOP.


apop($login,$pass)

Sends the POP3 APOP command to the server. The only allowable arguments are the name of the mailbox (login id) and the password. APOP is an OPTIONAL POP3 command. Not all servers support this method of authentication. As such, this may or may not work for your server. If authentication fails, this method will automatically use the login() method to authenticate. Returns false on failure, the number of messages in the mailbox on success, or -1 if unable to get the number of messages in the specified mailbox. This method can be disallowed by manually setting the global var ALLOWAPOP to false. See ALLOWAPOP in the VARIABLES section.


login($login = "", $pass = "")

Combined USER and PASS. Identical to using user() and pass() sequentially. The return values are the same as the pass() method.


noop()

Sends the POP3 NOOP command to the POP3 server. This command is implemented to allow clients to check the server for RFC 1939 compliance. The only response to this command is a '+OK' or a '-ERR', which indicate RFC 1939 compliance. Any other response from the server is invalid! This method has no other purpose, and is called automatically. If noop() is called before a user has authenticated, returns '-ERR'. The call to noop() must fail if the connection has not authenticated, and must succeed if the connection has authenticated. This POP3 class already implements this checking. If at any time a noop() call returns an inappropriate response, ERROR is set, the connect or login attempt will be aborted, and the connection to the server will be closed.


top($msgNum, $numLines = "0")

Sends the POP3 TOP command. Retrieves the message header and $numLines of the message body. Defaults to headers only. Set $numLines to -1 to retrieve the entire message contents. This method returns an array where each line of the message is an array element. Returns undef on failure. The TOP command is OPTIONAL per RFC 1939 and may not be supported by your server.


pop_list($msgNum = "")

Sends the POP3 LIST command to the server. This method returns the specified $msgNum's size in octets. If no message is specified, this method returns an associative array of undeleted message numbers as the keys, and the associated message size as the element. Array index zero will contain the total number of undeleted messages in the mailbox. Valid message numbers begin at array index one. Messages in the mailbox that are flagged for deletion will have their message size set to ``deleted''. This method returns undef (false) on failure.


get($msgNum)

Similar to TOP, this sends the POP3 RETR command. This method returns the contents of the specified message as an array, with each line of the message being an array element. Returns undef (false) on failure.


last( $type = "count" )

Sends the POP3 STAT command, which returns the number of undeleted messages in the mailbox. Valid arguments to last() are count and array. If the argument to last() is array, the method returns a 2 element array. Element zero will be the number of messages in the mailbox, and element one will be the mailbox total size in octets.


reset()

Sends the POP3 RSET command to the server. Returns true on success, false on failure. An RSET command is used to undelete a previously deleted message. This method is automatically called if the connection to the server is closed before a valid quit() call is sent. The RSET command can only undelete messages flagged for deletion during the currently open session and cannot undelete a message deleted during a previous session. This method automatcially closes the connection to the mail server. An RSET call implies that something bad has happened to the connection or the mailbox contents and automatically closes the connection to the server when called. A new connect() method must be called in order to re-establish the connection.


send_cmd( $cmd = "" )

This is an internal method, but can be called from your programs. Sends a user specified command to the POP3 server and returns a one line response. This method is useless if you need to read a multi-line response from the server. The command sent to the server should not include the carriage return line-feed pair as it will be supplied automatically by send_cmd(). The corresponding carriage return line-feed pair will be stripped from the returned reply automatically. If DEBUG is set to true, this command automatically logs the command and response via error_log(). See DEBUG for more information.


popstat()

Sends the POP3 STAT command with no arguments, which returns a 2 element array containing the total number of undeleted messages in the mailbox, and the size of the mailbox in octets. Returns undef on failure.


uidl($msgNum = "")

Sends the POP3 UIDL command to the server and returns it's output. The UIDL command is OPTIONAL per RFC 1939 and there-for may not be supported by your server. If given a message number, returns the UIDL for that message. If called with no arguments, returns an associative array containing undeleted message number keys and their associated UIDL elements. Returns undef on failure.


delete($msgNum = "")

Sends the POP3 DELE command to the server and returns a true or false response. This deletes a specified message number. If no message number is specified, returns false.


quit()

Sends the POP3 QUIT command to the server and closes the connection. You must call this method if you have deleted any messages. Failure to call this method before your program terminates will result in the mailbox being returned to the state it was in prior to your connection. This message recovery is implemented by the POP3 server and per RFC 1939 there's no way to override that unless you send the QUIT command.


is_ok($cmd = "")

Internal method. Examines the reply from a POP3 command looking for '+OK' or '-ERR' at the beginning of the response string. If there is anything other than '+OK' at the beginning of a response string, (and we're not looking at a multi-line response) will automatically be assumed to be a failure notice. Per RFC 1939 the first line of a POP3 server response MUST contain one of these two strings.


strip_clf($text = "")

Strips (all) CRLF's from the text submitted and returns the results. The first line of all server responses automatically have their CRLF stripped. Lines from a multi-line response are not stripped.


parse_banner( $server_text )

Internal method. This method parses the initial POP3 server response looking for the APOP banner. If found, parse_banner() automatically stashes the banner in the global variable BANNER. The BANNER is used as the common seed string in an apop() call per RFC 1939.


update_timer()

Internal method to reset the set_time_limit() with the current $TIMEOUT value.


VARIABLES


ERROR (string)

This variable contains the text of the last ERROR encountered. If a method fails, the text description of why the method failed can be retrieved by grabbing this variable.


$TIMEOUT (integer, default == 60)

The number of seconds to wait for a server response before giving up. Used with the PHP set_time_limit() function. Keep this fairly high, as downloading a 2 megabyte email over a modem is obviously going to take a few seconds. You may want to dynamically alter this value based upon message size. The timeout is set PRIOR to every POP3 command.


$COUNT (integer, default == -1)

After a successful login sequence, this variable contains the total number of messages in the mailbox at the time the user authenticated. Deleting messages in the mailbox will not alter this count. After deleting a message, you will need to call popstat() or list() to find out the total number of undeleted messages left in the mailbox.


$BUFFER (integer, default == 512)

Per RFC 1939, the largest line length returned by a POP3 server, including CRLF pairs, cannot exceed 512 bytes. When reading lines from a server response, the POP3 class uses fgets() to return the lines. fgets() stops reading the line when it encounters a new line, EOF, or $BUFFER number of bytes have been read.


$FP (file pointer, default == NULL)

This global maintains the open file pointer created by a successfull connect() method. Do not alter upon pain of death. This var is unset() if a connect() call fails, or if the quit() or reset() methods are called.


$MAILSERVER (string, default == NULL)

This global is set to null for the life of the process. If you want to HARD CODE the server that this class is allowed to use, then edit the source and specify the server name. Once the server is specified, the class will ignore any server specified in a connect(), new(), or POP3() method call and will always use the server pointed to by $MAILSERVER.


$DEBUG (boolean, default == false)

If set to true, the command - response pairs of all POP3 commands will be logged via error_log(). This logging is usually captured by your web server and stored someplace like /var/log/httpd/error_log. WARNING. If DEBUG is set to true, ALL commands, and the initial response to those commands, get logged. This means that login id and password pairs are logged as plain text. Obviously this is not something you want to enable if you are at all concerned with server security.


$BANNER (string, default == NULL)

The $BANNER var contains the results of the parse_banner() call. This is the common seed value for the creation of an MD5 hash used for APOP authentication.


$ALLOWAPOP (boolean, default == false)

Set to true if you want to allow APOP authentication. If the server does not support APOP, set this to false. Most POP3 servers will deliberately impose a random delay in response to a failed APOP attempt. This is an effort to thwart brute force password cracking. As such, it can substantially slow down your program if it tries to do APOP authentication on a server that does not support it.


RFC1939 (boolean, default == true)

Do not attempt to change this variable manually. This boolean value contains the results of the last noop() call made within the class. The noop() call MUST return false before authentication, and MUST return true after authentication. These checks are already handled by this class. See noop() and the rfc1939.txt for more information.


EXAMPLES

see SYNOPSIS


DOCUMENTATION

Included with the archive is rfc1939.txt. Read it before sending me a question. Please. :)


INSTALLATION

Copy the class file to the location specified in your PHP3.INI file. Failing that, use the full path to the class file's location in your include() directive.


BUGS

APOP has not been tested. None of the servers I have access to support it. In theory it should work, as the RFC is very rigid in how APOP is implemented, but of course, YMMV.


VERSION

Version 1.0 1999/03/24 CDI, cdi@thewebmasters.net


AUTHOR

Copyright (c) 1999, CDI - cdi@thewebmasters.net. All Rights Reserved.


LICENSE

This program is free software; you can redistribute it and/or modify it under the GNU General Artistic License, with the following stipulations;

Changes or modifications must retain these Copyright statements. Changes or modifications must be submitted to the AUTHOR, cdi@thewebmasters.net.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Artistic License for more details. This software is distributed AS-IS.


AVAILABILITY

http://www.thewebmasters.net/php/


HISTORY

Version 1.0, initial public release