POP3 1.0 - An RFC 1939 compliant PHP wrapper to the POP3 protocol
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;
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.
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.
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.
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.
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.
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.
Combined USER and PASS. Identical to using user()
and pass()
sequentially. The return values are the same as the pass()
method.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Internal method to reset the set_time_limit()
with the current $TIMEOUT
value.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
see SYNOPSIS
Included with the archive is rfc1939.txt. Read it before sending me a question. Please. :)
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.
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 1.0 1999/03/24 CDI, cdi@thewebmasters.net
Copyright (c) 1999, CDI - cdi@thewebmasters.net. All Rights
Reserved.
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.
http://www.thewebmasters.net/php/
Version 1.0, initial public release