Richard York

Web Developer, Author, and Artist


bool getParts(int &$mid, [str &$pid = '0'[, bool $rtn = FALSE[, array $args = array()]]])

Mail_IMAP::getParts scans the structure of a message and sorts out the relevant attachments and inline parts. getParts may be used in two ways, to produce threaded messages in a fashion similar to that of Microsoft Outlook, where when a message part is viewed only the children attachments and inline parts relevant to that part are retrieved, or it can be used to retrieve all of the attachments and inline parts of the entire message. By default getParts retrieves attachments and inline parts in the former threaded method. Threading can be turned off by adding an associative indice to the optional $args argument as array('retrieve_all' => TRUE).

When getParts is called, the information it gathers is placed in the $msg property, which is a multidimensional array offset in the first level of nesting by message number and then in the second level of nesting by two associate indices labeled 'in' and 'at' respectively. Inline parts commonly are parts related to the current message, as in the case of the multipart/related MIME type, or may be the alternative part of a multipart/alternative message, or inline parts can be entire attached messages, attached messages can show up in either the 'in' or 'at' arrays depending on how the sending program constructs the message.

A third level of nesting is also present in the array where fields of information about each part are stored, such as the file name, the MIME type, the file size and other such information. The fields that are available may be customized by specifiying each field in the $fields property, which controls the fields that are parsed into the 'in' and 'at' arrays of the $msg property.

By default Mail_IMAP retrieves both parts of a multipart/alternative message, which can be useful for debugging applications that send out multipart mail. The text/html part is given priority over the text/plain part. If an alternative part is present, it is placed in the 'in' array. To turn off retrieval of the alternative part, add an associative indice to the $args argument as array('get_alternative' => FALSE).

Likewise, which part given priority in a multipart/alternative message can also be customized. By default, Mail_IMAP always looks for text/html parts first. This can be reversed so that it always looks for a text/plain part first by adding an associative indice to the $args argument as array('get_mime' => 'text/plain').

If no $pid argument is supplied to getParts, it will scan for top level inline parts and attachments only (assuming the retrieve_all argument is the default of FALSE) . To return the inline parts and attachments of a specific part, pass the $pid of that message to getParts.

getParts returns boolean by default. To return the contents of the $msg property instead, set the optional $rtn argument TRUE.

getParts is also used to retrieve the part number of the message designated the top-level part, in Mail_IMAP this is referred to as the default PID. The default PID is the part number used to link to the main message itself this part id is also available in the $msg property, in the third level of nesting as associative indice 'pid', for instance $this->msg[$mid]['pid']. IMAP.inbox.php demonstrates how this id is embedded in the link applied to the subject of each message to view the message itself.

IMAP.part_viewer.php demonstrates how the part id is passed back to getParts when viewing a specific message part to retrieve only the attachments and inline parts that are children of that part.

Internally, getParts calls on two methods, Mail_IMAP::_checkIfParsed() (protected) and Mail_IMAP::_scanMultipart() (private).

Retrieving attachments and linking up messages with getParts

The following example shows how getParts is used to link up to the messages in your mailbox.

<?php require_once 'Mail/IMAP.php'; $msg =& new Mail_IMAP(); // Open up a mail connection if (!$msg->connect('imap://'.urlencode('').'')) { echo "<span style='font-weight: bold;'>Error:</span> Unable to build a connection.<br/> "; echo $msg->alerts(); echo $msg->errors(); // See if ErrorStack has any errors. if ($msg->error->hasErrors()) { echo "<pre> "; var_dump($msg->error->getErrors(TRUE)); echo "</pre> "; } } // Retrieve the message count. $cnt = $msg->messageCount() // Make a loop that iterates for each message in the mailbox // This example shows how top-level messages are retrieved // In c-client, messages are always numbered offset from 1 for ($mid = 1; $mid < $cnt; $mid++) { // Get Parts // Retrieved information is stored in the $msg property. $msg->getParts($mid); // Get Headers // Retrieved information is stored in the $header property. $msg->getHeaders($mid); // This link contains the message id and part id, which // must be passed to the part viewer script. // The default PID is in the $msg->[$mid]['pid'] // property. This is the message part you see // when you click on a message. echo "<a href="IMAP.message_viewer.php?mid=&pid={$msg->msg[$mid]["pid']}'> ". $msg->header[$mid]['subject']. "</a><br/> "; // See if there are any inline parts, if there are // display those first. if (isset($msg->msg[$mid]['in']) && count($msg->msg[$mid]['in']) > 0) { foreach ($msg->msg[$mid]['in']['pid'] as $i => $inid) { echo "Inline part: ". "<a href="IMAP.message_viewer.php?mid=&pid=".$msg->msg[$mid]['in']['pid'][$i]."'> ". $msg->msg[$mid]['in']['fname'][$i]." ". $msg->msg[$mid]['in']['ftype'][$i]." ". $msg->convertBytes($msg->msg[$mid]['in']['fsize'][$i]). "</a><br /> "; } } // Next, see if there are any attachment parts if (isset($msg->msg[$mid]['at']) && count($msg->msg[$mid]['at']) > 0) { foreach ($msg->msg[$mid]['at']['pid'] as $i => $atid) { echo "Attachment: ". "<a href="IMAP.message_viewer.php?mid=&pid=".$msg->msg[$mid]['at']['pid'][$i]."'> ". $msg->msg[$mid]['at']['fname'][$i]." ". $msg->msg[$mid]['at']['ftype'][$i]." ". $msg->convertBytes($msg->msg[$mid]['at']['fsize'][$i]). "</a><br /> "; } } echo "<br/> "; } ?>

Method summary:

param int &$mid message id
param str &$pid (optional) Part id.
param bool $rtn (optional) See above.
param array $args (optional) See. above.
return bool|array Returns the contents of the $msg property if the optional $rtn argument is TRUE.
throws ErrorStack: Invalid part id. The method was unable to find a part in the message that corresponds to the part id that was passed.
access public
since PHP 4.2.0
see $msg


There are no comments posted at this time.

Leave a Comment

Simple HTML is allowed: <code>, <b>, <i>, <u>, <var>, <strong>, <em>, <blockquote>, <ul>, <ol>, <li>, <p> (no attributes). All spacing and line breaks in your comment will be preserved.

* All comments are moderated and are subject to approval.
Your comment will appear once it has been approved.
Posting multiple times will not expedite the approval process.

Comments are closed at this time.

© Copyright 2014 Hot Toddy, All Rights Reserved.