Peeker

Peeker Quickstart

IMAP examples

First, make sure your PHP install has the imap extension (run phpinfo() and search for imap).

Note: this Quick Start assumes you are using Peeker as a CodeIgniter library. If you are using Codeigniter, just place all the Peeker files in the application/libraries directory and load the library using CI's $this->load->library('peeker') method.

However, Peeker can work as a standalone set of classes. Just use the PHP "include" command like this: include('peeker.php'); and modify the syntax for the examples below to use regular PHP Object Oriented coding.

So, instead of $this->load->library('peeker', $config);
// call a method on the CI peeker object
$this->peeker->somefunction(); just do $peeker = new peeker($config);
// call method on the regular PHP peeker object
$peeker->somefunction();

First, create a new controller function with this code (change login info to match your IMAP login).

// this shows basic IMAP, no TLS required
$config['login']='IMAP_username';
$config['pass']='IMAP_password';
$config['host']='imap.domain.com';
$config['port']='143';
$config['service_flags'] = '/imap/notls';

$this->load->library('peeker', $config);

if ($this->peeker->message_waiting())
{
echo 'Message count:' . $this->peeker->get_message_count();
}
else
{
echo 'No messages waiting.';
}

$this->peeker->close();

// tell the story of the connection
print_r($this->peeker->trace());

If you have unread email in the account, you should see a message with the number of unread emails waiting at the server.

You can connect to any POP or IMAP server. This next config shows how to connect to the gmail.com IMAP server. This example requires that PHP be compiled with SSL. You can verify this with phpinfo().

Important:  You must enable IMAP on your gmail account. Go to your gmail account and click 'Settings'. Then click 'Forwarding and POP/IMAP'. Scroll down to 'IMAP Access' and check 'Enable IMAP' and click Save Changes

// gmail IMAP
$config['login']='your_username@gmail.com';
$config['pass']='your_password';
$config['host']='imap.gmail.com';
$config['port']='993';
$config['service_flags'] = '/imap/ssl/novalidate-cert';

POP Examples

Basic POP

// Basic POP
$config['login']='POP_username';
$config['pass']='POP_password';
$config['host']='mail.domain.com';
$config['port']='110';
$config['service_flags'] = '/pop3/notls';

This next example shows settings that will connect to gmail's POP server. Just like in the IMAP example, PHP must be configured with SSL for this to work.

Important:  You must enable POP on your gmail account. Go to your gmail account and click 'Settings'. Then click 'Forwarding and POP/IMAP'. Scroll down to 'POP Download' and check 'Enable POP for all mail' (if this is a new gmail account with no messages) OR 'Enable POP for mail that arrives from now on' (if this is an existing gmail account with lots of messages) and click Save Changes

gmail POP

// gmail POP
$config['login']='your_username@gmail.com';
$config['pass']='your_password';
$config['host']='pop.gmail.com';
$config['port']='995';
$config['service_flags'] = '/pop3/ssl/novalidate-cert';

Some Peeker Functions

This is a selection of Peeker Class functions - it is not complete, but should get you started exploring.

$this->peeker->get_message(message_number)

Get a message in the queue. Returns a message object. The example below uses 1 as the parameter so the code gets the first message waiting. NOTE: Message number index starts at 1. Sending 0 to this method will result in a stream of notices and print a message in the log trace.

$e = $this->peeker->get_message(1);

$this->peeker->delete_and_expunge(message_number)

Delete and Expunge the first message in the queue.

$this->peeker->delete_and_expunge(1);

$this->peeker->close([TRUE])

Close the connection and (optionally) Expunge any messages that have been marked to delete. (see $e->set_delete() below)

// sending TRUE as first parameter
// tells the server to expunge on close
$this->peeker->close(TRUE);

Some Message Object Functions

This is a selection of Peeker Message Object functions (available in the message object) - it is not a complete listing, but it shows enough to let you get a taste of what's possible. A complete listing is available in the Peeker Header, the Peeker Body, the Peeker Parts, or the Peeker File documentation.

Important:  Call the following functions using the message object returned by $this->peeker->get_message(). In these examples it is called $e.

$e->get_subject()

Get the subject of the message.

// get the first message in the queue
$e = $this->peeker->get_message(1);
echo $e->get_subject();

$e->get_date()

Get the date of the message.

// get the first message in the queue
$e = $this->peeker->get_message(1);
echo $e->get_date();

$e->get_from()

Get the from string of the message.

// get the first message in the queue
$e = $this->peeker->get_message(1);
echo $e->get_from();

$e->get_to()

Get the to string of the message.

// get the first message in the queue
$e = $this->peeker->get_message(1);
echo $e->get_to();

$e->get_size()

Get the size (in bytes) of the message.

// get the first message in the queue
$e = $this->peeker->get_message(1);
echo $e->get_size();

$e->get_header_array()

Get the entire header (as associative array) of the message.

// get the first message in the queue
$e = $this->peeker->get_message(1);
echo $e->get_header_array();

$e->set_delete()

Mark a message in the queue for deletion. Does not automatically delete. You must call $this->peeker->close(TRUE) and send TRUE as the first parameter.

// mark the first message for deletion
$e = $this->peeker->get_message(1);
$e->set_delete();
$this->peeker->close(TRUE);

$e->get_plain()

Get the plain part (plain text of the email body) of the message.

// get the first message in the queue
$e = $this->peeker->get_message(1);
echo $e->get_plain();

$e->get_html()

Get the HTML part (HTML text of the email body) of the message.

// get the first message in the queue
$e = $this->peeker->get_message(1);
echo $e->get_html();

$e->get_parts_array()

Get the parts array (all attachments, including PLAIN and HTML attachments) of the message. Each array item is a peeker_file object. The file object has information about each body part and attachment. Dump it to see the structure.

// get the first message in the queue
$e = $this->peeker->get_message(1);
print_r($e->get_parts_array());

That is a short summary of some useful functions in Peeker. There are many, many more functions available. Look at the class documentation to learn.

This guide focused on functions; there are other capabilities in the class that were not covered at all in this quickstart: using detectors to write declarative programs, peek at headers (don't disturb read state of message) by setting message class to peeker_header, extend message object class to create your own detectors.

Requirements: