Peeker Class

Please look at the Quickstart Guide first. This page documents the entire Peeker main class and shows advanced techniques. The Quickstart Guide is a better place to start if you are using Peeker for the first time.

This is the main Peeker class. It extends the Peeker Connect class to connect to a POP or IMAP server and get emails.

Once connected, you can get header information for any email messages. This class lets you "peek" at email headers without disturbing the "read" state of the message and without downloading any of the email body or attachments.

Note: The message handling can be changed so this class will get only message headers (saves memory and time by not getting bodies and attachments). See the set_message_class() method below.

Features:

Everything the Peeker Connect class can do, plus...
Count the number of messages waiting.
Get all email headers from one message into one object.
Decode MIME encoded email headers.
Set IMAP search parameters and get list of message IDs matching the search.
Do not disturb the read state of the message (good for gMail POP).
Event System: Detector-Callback circuits in the email acquisition loop.

Count the new messages waiting at IMAP or POP server

Enter your mailserver connection data and run a few lines of code.

Example IMAP connection

Connect to the gMail.com IMAP server using the Peeker class (remember to enable IMAP on your gmail account):


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

	

	$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';

	

	$this->peeker->initialize($config);

	if ($this->peeker->message_waiting())

	{

		echo 'Message count:' . $this->peeker->get_message_count();

	}

	else

	{

		echo 'No messages waiting.';

	}

	

	$this->peeker->close();

	

	// now tell us the story of the connection

	print_r($this->peeker->trace());

Get first email and pull headers from the message object

Assuming you've already connected and initialized as above:

Note: This code shows only a few of the headers available.


	
	if ($this->peeker->message_waiting())

	{

		// get the first message 

		$email = $this->peeker->message(1);

		echo $email->Msgno;

		echo $email->date;

		echo $email->subject;

		echo $email->toaddress;

		echo $email->fromaddress;

	}

Header fields in message object

This class brings all email header data into one convenient object. See the PHP manual pages for documentation on the two PHP IMAP class header functions: imap_headerinfo() and imap_fetch_header()

Peeker combines the output of these two header functions. This is because the raw email header always holds more header fields than those returned by imap_headerinfo(). Peeker makes it easy to gather, decode, and access all of those header fields.

The headers returned by the PHP function imap_headerinfo() are put directly into the email message object. The header fields are mapped directly to message object properties. See the PHP manual page imap_headerinfo() function for a list of headers (and Peeker Message Object properties) that are available after calling message().

Additionally, two other properties are added to the message object. These are two versions of the raw header returned by imap_fetch_header(): header_string and header_array. The first is the raw header string and the second is the raw header parsed into a multi-dimensional, associative array of header fields. They both contain the same header data.

// an example of the header_array property of the message object[header_array] => Array
(
	[Delivered-To] => you@domain.com
	[Received] => Array
	(
		[0] => by 123.123.123.123 with SMTP id 8; 
		Sat, 27 Jun 2009 06:44:39 -0700 (PDT)
		[1] => by 123.123.123.123 with SMTP id 6; 
		Sat, 27 Jun 2009 06:44:38 -0700 (PDT)
		[2] => from abc.def.ghi.jkl (abc.def.ghi.jkl [1.1.1.1]) 
		by mx.google.com with ESMTP id 9; 
		Sat, 27 Jun 2009 06:44:38 -0700 (PDT)
	)

	[Return-Path] => bounce@domain.com
	[Received-SPF] => neutral (google.com: 1.2.3.4 is neither 
	permitted nor denied by best guess record for domain of 
	me@domain.com) client-ip=1.2.3.4;
	[Authentication-Results] => mx.google.com; spf=neutral 
	(google.com: 1.2.3.4 is neither permitted nor denied by 
	best guess record for domain of me@domain.com) 
	smtp.mail=me@domain.com
	[Date] => Sat, 27 Jun 2009 09:44:36 -0400
	[From] => Full Name <me@domain.com>
	[Subject] => text file attached
	[To] => you@domain.com
	[Message-id] => mxylplyx
	[MIME-version] => 1.0
	[X-Mailer] => Apple Mail (2.935.3)
	[Content-type] => multipart/mixed; boundary="Boundary_(ID_iS)"
)

The raw header string is from PHP's imap_fetch_header() function and Peeker creates the multi-dimensional array.

Also, you can always dump the message object to see what's in there. Every message has a different set of headers so it's good practice to get to know email headers.

Function Reference

get_message($start [,$end])

This is the function if you simply want the Peeker class to get entire email messages from a POP or IMAP server.

After loading the library, call get_message() to get a message. The get_message() function gets the whole message (header, body and attachments/parts). It is a wrapper function for the message() function below. However, it does not just "peek" at the messages, it "pulls" them (headers, body, and attachments) and they will be downloaded and/or marked as read. 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.

You can pass 1 or 2 parameters. 1 parameter means "get one message" indicated by the integer passed, and 2 parameters means "get a range of messages."

Returns one object (if only $start sent) or an array of message objects (if $start and $end sent). This method spawns message objects as either stdClass objects or custom class objects (see set_message_class() method below to define your own objects).

// get the whole first email message

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

// get the first 5 email messages - all data in the email

$email_array = $this->peeker->get_message(1,5);

Technical note: The get_message() function loads up the peeker_parts class and the detector class. It then creates a single detector that runs the acquisition function that "pulls" the email.

message($start [,$end])

After loading the library, call message() to just peek at message headers. Note: message() will download and mark as read if the message class is peeker_body, peeker_parts, or an extension of either.

Just like get_message(), you can pass 1 or 2 parameters. 1 parameter means "get one message" indicated by the integer passed, and 2 parameters means "get a range of messages." 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.

Returns one object (if one parameter sent) or an array of message objects (if 2 parameters sent). This method spawns either stdClass objects or custom class objects (see set_message_class() method below to define your own objects).

// get just the headers of the first email message

$email_object = $this->peeker->message(1);

// get just the headers of the first 5 email messages

$email_array = $this->peeker->message(1,5);

set_search($search_string)

Set an IMAP search string. See the PHP Manual Page for imap_search() to see the types of searches you can do.

// set the IMAP search terms

$this->peeker->set_search('TO "name@email.com"');

search_and_count_messages()

Sends the search to the IMAP server. Returns the number of messages found.

// do the IMAP search, return count of messages found.

$this->peeker->search_and_count_messages();

get_ids_from_search([$index])

Get the list of Msgnos found by the search (note: these are not message IDs). Returns an array of Msgnos of messages found by the search.

Loop over the array and get each message by calling the message() method with the Msgno as the parameter.

Send optional $index parameter to get just one Msgno (e.g., get_ids_from_search(0) returns the first Msgno found).

// set the IMAP search terms

$this->peeker->set_search('FROM "othername@email.com"');

// do the IMAP search, return count of messages found.

$search_count = $this->peeker->search_and_count_messages();

// do the IMAP search, return count of messages found.

$id_array = $this->peeker->get_ids_from_search();

decode_mime($encoded_string)

Email message headers and parts are often encoded using the MIME standard (Wikipedia Article on MIME). This function helps you to decode MIME-encoded strings.

Returns a MIME-decoded string.

Note: you can send an unencoded string and you will get that string back.

$email = $this->peeker->message(1);

$decoded_subject = $this->peeker->decode_mime($email->subject);

The Peeker class can automatically decode individual MIME-encoded header fields but does not do so unless you

use the get_message() function or...
set your own message class.

You can use the decode_mime() method on a message header string or you can use set_message_class() to set a custom message class that does the decoding.

The custom class can be set up to automatically handle MIME decoding tasks per message. See the Peeker Header class for an example custom class that does automatic MIME decoding. Or, just use get_message().

set_message_class($classname=filename minus extension)

Before getting messages from the mailserver you can tell the Peeker Class which class you want to use to hold and process the messages. This is useful for creating custom message handling methods.

For example, the Peeker Header "spawn" class automatically MIME-decodes header parts. It also provides methods to access all the header fields.

Note: if you set a custom class, there must be a file with the name and a .php extension located in the same directory with the Peeker class. Additionally, you must use the message() method - not the get_message() method. This is because the get_message() method automatically loads the peeker_parts header class.

//peeker_header.php file must be in same directory

$this->peeker->set_message_class('peeker_header');

If you don't set the message class (and you don't use the get_message() function), Peeker uses PHP's native stdClass object for incoming emails.

delete_and_expunge($message_number)

Delete the message and expunge it. Deleting mail from an IMAP or POP mailserver happens in two stages: deleting and expunging. This method lets you do both at the same time.

Call it only when you are sure you want to delete the message from the mailserver. There is no undo.

// delete the first message

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

Note: the gMail POP and IMAP interfaces ignore this command and do not delete the message. gMail has its own internal email handling system that works different from normal POP and IMAP servers. You can change how gMail handles IMAP- and POP-accessed messages in the Settings tab at gmail.com.

set_attachment_dir($writeable_directory)

Set a directory to hold email attachments. This is a utility function that custom classes can use to create file handling methods. Returns TRUE on success.

$bool = $this->peeker->set_attachment_dir(APPPATH.'attachments');

Note: Directory must be writeable.

get_attachment_dir()

Get the directory that holds email attachments. This is a utility function that custom classes can use for file handling methods. Returns the directory path that was set.

$dir = $this->peeker->get_attachment_dir();

Detectors

The Peeker Detector system processes email in a declarative programming style. This style helps you modularize reuseable detector components. Declarative programming can also help you split tasks among multiple programmers and make your program logic clear.

Note: The Peeker Detector system only works if:

you use the get_message() function or...
you create a custom message class and tell Peeker to use it

$this->peeker->set_message_class('peeker_header'); Consider it an advanced, powerful and completely optional technique.

make_detector_set()

Create and return a detector set object that will hold all the detectors.


$detector = $this->peeker->make_detector_set();

The detector set and its detectors must be created before calling the get_message() or message() method. See peeker_detector class documentation for complete examples.

detectors_abort($state)

Tell the detector loop to abort immediately. Send TRUE or FALSE.


$this->peeker->detectors_abort(TRUE);