[commits] [Wiki] changed: Doc/Dev/Imap_Client/Examples

[Michael Slusarz]

slusarz  Thu, 27 Feb 2014 06:45:04 +0000

Modified page: http://wiki.horde.org/Doc/Dev/Imap_Client/Examples
New Revision:  3
Change log:  Add notes that I will hopefully eventually add to the tutorial

@@ -1,11 +1,13 @@
  + Horde/Imap_Client usage examples

-++ Assumptions
+++ Examples
+
++++ Assumptions

  In these examples, {{$imap}} is assumed to be a previously  
configured/created Client object.

-+++ Get a list of messages in INBOX, since a certain date:
+++++ Get a list of messages in INBOX, since a certain date:
  <code type="php">
  $query = new Horde_Imap_Client_Search_Query();
  $query->dateSearch(
      new Horde_Date($date_string),
@@ -18,9 +20,9 @@
  // A Horde_Imap_Client_Ids object containing the list of UIDs that  
matched the query.
  var_dump($results['match']);
  </code>

-+++ Using the above message ids, fetch the plaintext body of the first email:
+++++ Using the above message ids, fetch the plaintext body of the  
first email:
  <code type="php">
  $query = new Horde_Imap_Client_Fetch_Query();
  $query->structure();

@@ -52,5 +54,105 @@
      $text = $body->getContents();
  }

  // $text now contains the plaintext body of the message.
+</code>
+
+++ TODO (Notes that will eventually be converting to the tutorial)
+
+<code type="php">
+// Need UIDVALIDITY to pair with UIDs to ensure that future calls are  
referring
+// to the same UID.  We can get the UIDVALIDITY for a mailbox like this:
+$status = $client->status('INBOX', Horde_Imap_Client::STATUS_UIDVALIDITY);
+$uidvalidity = $status['uidvalidity'];
+// UID + UIDVALIDITY = unique 64-bit number for a mailbox on a given server
+// See: http://tools.ietf.org/html/rfc3501#section-2.3.1.1
+
+
+// $results is an array.  The list of UIDs is in the 'match' key.  It  
is a Horde_Imap_Client_Ids object:
+//  
http://dev.horde.org/api/master/lib/Imap_Client/classes/Horde_Imap_Client_Ids.html
+
+// This object is Traversable (via foreach()).  You can also call  
count() on the object.
+// The raw list of UIDs (in array format) is available via the $ids property.
+// i.e. $results['match']->ids gets the list of UIDs.
+
+// Read an attachment from a message.
+// From the UIDs result above, pick one of the UIDs.  I will call that $uid.
+// First we need to get the structure of that message to determine  
what parts we want to load.
+
+// To fetch information, we use the Horde_Imap_Client_Fetch_Query  
class to build the fetch query.
+//  
http://dev.horde.org/api/master/lib/Imap_Client/classes/Horde_Imap_Client_Fetch_Query.html
+
+$query = new Horde_Imap_Client_Fetch_Query();
+// This fetches the structure:
+$query->structure();
+
+// Now we are ready to fetch() the message info from the server.
+//  
http://dev.horde.org/api/master/lib/Imap_Client/classes/Horde_Imap_Client_Base.html#method_fetch
+
+$results = $client->fetch('INBOX', $query, array(
+     // We want to limit results to a single UID (default is ALL UIDs).
+     'ids' => new Horde_Imap_Client_Ids($uid)
+));
+
+// $results is a Horde_Imap_Client_Fetch_Results object:
+//  
http://dev.horde.org/api/master/lib/Imap_Client/classes/Horde_Imap_Client_Fetch_Results.html
+
+// To get the results for a particular ID, we can use array syntax:
+$uid_result = $results[$uid];
+
+// $uid_result now contains the Horde_Imap_Client_Data_Fetch object  
for UID $uid
+//  
http://dev.horde.org/api/master/lib/Imap_Client/classes/Horde_Imap_Client_Data_Fetch.html
+
+// To retrieve the structure object, we call this:
+$structure = $uid_result->getStructure();
+
+// $structure now contains the Horde_Mime_Part object representing  
the base part of the object.
+// http://dev.horde.org/api/master/lib/Mime/classes/Horde_Mime_Part.html
+// See also: http://wiki.horde.org/Doc/Dev/MimeH4
+
+// Assuming this structure for the message:
+// multipart/related
+//   + text/plain
+//   + text/html
+// To get list of parts in base $structure object:
+$parts = $structure->contentTypeMap();
+
+// $parts = array(
+//     ['1'] => text/plain
+//     ['2'] => text/html
+// )
+
+// Consumer (client) code determines we want to view the HTML part,  
for example (part ID 2).  So we need to grab this data from the
+// IMAP server.
+$query = new Horde_Imap_Client_Fetch_Query();
+$query2->bodyPart('2', array(
+     // Set this to true if you don't want the \Seen flag to be set
+     'peek' => false
+));
+$results = $client->fetch('INBOX', $query2, array(
+     'ids' => new Horde_Imap_Client_Ids($uid)
+));
+
+// This returns the body part data in a stream (recommended to reduce  
memory usage; if second argument is false,
+// data will be returned as string).
+$stream = $results[$uid]->getBodyPart('2', true);
+
+// $stream is raw data of part.  It may be transfer-encoded (i.e. base64).
+// To decode, we need to add data to Horde_Mime_Part object containing
+// structure of this part.  We already have this information - we  
retrieved it back with the structure data.
+$part = $structure['2'];
+// $part is now the Horde_Mime_Part object of the text/html (ID 2) part.
+$part->setContents($stream, array(
+     // This is more efficient; it reuses the $stream from above  
rather than copying data. It should be used
+     // if we know that $stream won't be altered by any other process.
+     'usestream' => true
+));
+
+// Now, to get the binary data of the part ($html_data is a string).
+$html_data = $part->getContents();
+
+// To return $html_data as a stream (more memory efficient):
+$html_data = $part->getContents(array(
+     'stream' => true
+));
  </code>