arbitrary mime-parts: added support for listing/receiving any mime part of message (can be used e.g. for parsing DSNs)

Author: jkuchar

MailLibrary/Drivers/ImapDriver.php

@@ -301,22 +301,39 @@ public function getStructure($mailId, Mailbox $mailbox)
 	 * Gets part of body
 	 *
 	 * @param int   $mailId
-	 * @param array $data
+	 * @param array $data requires id and encoding keys
 	 * @return string
+	 * @throws \greeny\MailLibrary\DriverException
 	 */
 	public function getBody($mailId, array $data)
 	{
 		$body = array();
 		foreach($data as $part) {
-			$data = ($part['id'] == 0) ? imap_body($this->resource, $mailId, FT_UID | FT_PEEK) : imap_fetchbody($this->resource, $mailId, $part['id'], FT_UID | FT_PEEK);
-			$encoding = $part['encoding'];
-			if($encoding === ImapStructure::ENCODING_BASE64) {
-				$data = base64_decode($data);
-			} else if($encoding === ImapStructure::ENCODING_QUOTED_PRINTABLE) {
-				$data = quoted_printable_decode($data);
+			assert(is_array($part));
+			$dataMessage = ($part['id'] === 0) ? @imap_body($this->resource, $mailId, FT_UID | FT_PEEK) : @imap_fetchbody($this->resource, $mailId, $part['id'], FT_UID | FT_PEEK);
+			if($dataMessage === FALSE) {
+				throw new DriverException("Cannot read given message part - " . error_get_last()["message"]);
+			}
+
+			// when there is no encoding of mime part available
+			if(!isset($part['encoding'])) {
+				$decodedMessage = $dataMessage;
+
+			} elseif($part['encoding'] === ImapStructure::ENCODING_BASE64) {
+				$decodedMessage = base64_decode($dataMessage);
+				if($decodedMessage === FALSE) {
+					throw new DriverException('Malformed mime-part: cannot decode base64 mime-part');
+				}
+
+			} elseif($part['encoding'] === ImapStructure::ENCODING_QUOTED_PRINTABLE) {
+				$decodedMessage = quoted_printable_decode($dataMessage);
+
+			} else {
+				throw new DriverException("Mime-part reading error: unknown encoding ({$part['encoding']})");
+
 			}
 
-			$body[] = $data;
+			$body[] = $decodedMessage;
 		}
 		return implode('\n\n', $body);
 	}

MailLibrary/Mail.php

@@ -193,6 +193,15 @@ public function getAttachments()
 		return $this->structure->getAttachments();
 	}
 
+	/**
+	 * @return \greeny\MailLibrary\MimePart[]
+	 */
+	public function getMimeParts()
+	{
+		$this->structure !== NULL || $this->initializeStructure();
+		return $this->structure->getMimeParts();
+	}
+
 	/**
 	 * @return array
 	 */
@@ -257,6 +266,15 @@ protected function initializeStructure()
 		$this->structure = $this->connection->getDriver()->getStructure($this->id, $this->mailbox);
 	}
 
+	/**
+	 * @internal
+	 * @return IStructure
+	 */
+	public function getStructure() {
+		$this->structure !== NULL || $this->initializeStructure();
+		return $this->structure;
+	}
+
 	protected function initializeFlags()
 	{
 		$this->connection->getDriver()->switchMailbox($this->mailbox->getName());

MailLibrary/MimePart.php

@@ -0,0 +1,82 @@
+<?php
+/**
+ * This file is part of the imap-mail-list-extractor.
+ * Copyright (c) 2017 Grifart spol. s r.o. (https://grifart.cz)
+ */
+
+namespace greeny\MailLibrary;
+
+use greeny\MailLibrary\Drivers\IDriver;
+
+class MimePart
+{
+	/** @var string */
+	private $partId;
+
+	/** @var string */
+	private $mimeType;
+
+	/** @var string */
+	private $name;
+
+	/** @var string */
+	private $encoding;
+
+	/** @var IDriver */
+	private $driver;
+
+	/** @var string */
+	private $mailId;
+
+	public function __construct(IDriver $driver, $mailId, $partId, $mimeType, $name, $encoding)
+	{
+		$this->partId = $partId;
+		$this->mailId = $mailId;
+		$this->mimeType = $mimeType;
+		$this->name = $name;
+		$this->encoding = $encoding;
+		$this->driver = $driver;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function getPartId()
+	{
+		return $this->partId;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function getMimeType()
+	{
+		return $this->mimeType;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function getName()
+	{
+		return $this->name;
+	}
+
+	/**
+	 * @return string
+	 */
+	public function getEncoding()
+	{
+		return $this->encoding;
+	}
+
+	public function getContent()
+	{
+		// todo: this automatically decodes content type if supported, support for getting RAW content?
+		return $this->driver->getBody($this->mailId, [[
+			'id'       => $this->partId,
+			'encoding' => $this->encoding,
+		]]);
+	}
+
+}

MailLibrary/Structures/IStructure.php

@@ -6,6 +6,7 @@
 namespace greeny\MailLibrary\Structures;
 
 use greeny\MailLibrary\Attachment;
+use greeny\MailLibrary\MimePart;
 
 interface IStructure {
 	/**
@@ -27,4 +28,9 @@ function getTextBody();
 	 * @return Attachment[]
 	 */
 	function getAttachments();
-}
+
+	/**
+	 * @return MimePart[]
+	 */
+	function getMimeParts();
+}

MailLibrary/Structures/ImapStructure.php

@@ -8,6 +8,7 @@
 use greeny\MailLibrary\Attachment;
 use greeny\MailLibrary\Drivers\ImapDriver;
 use greeny\MailLibrary\Mailbox;
+use greeny\MailLibrary\MimePart;
 
 class ImapStructure implements IStructure {
 	const TYPE_TEXT = 0;
@@ -37,6 +38,9 @@ class ImapStructure implements IStructure {
 		self::TYPE_OTHER => 'other',
 	);
 
+	/** @var MimePart[] */
+	private $mimeParts = [];
+
 	/** @var \greeny\MailLibrary\Drivers\ImapDriver */
 	protected $driver;
 
@@ -64,6 +68,9 @@ class ImapStructure implements IStructure {
 	/** @var Mailbox */
 	protected $mailbox;
 
+	/** @var array */
+	private $rawStructure = [];
+
 	/**
 	 * @param ImapDriver $driver
 	 * @param object     $structure
@@ -72,6 +79,7 @@ class ImapStructure implements IStructure {
 	 */
 	public function __construct(ImapDriver $driver, $structure, $mailId, Mailbox $mailbox)
 	{
+		$this->rawStructure = $structure;
 		$this->driver = $driver;
 		$this->id = $mailId;
 		$this->mailbox = $mailbox;
@@ -84,6 +92,15 @@ public function __construct(ImapDriver $driver, $structure, $mailId, Mailbox $ma
 		}
 	}
 
+	/**
+	 * @return array
+	 * @internal use only with caution, format can change without warning
+	 */
+	public function getRawStructure()
+	{
+		return $this->rawStructure;
+	}
+
 	/**
 	 * @return string
 	 */
@@ -100,9 +117,9 @@ public function getHtmlBody()
 		if($this->htmlBody === NULL) {
 			$this->driver->switchMailbox($this->mailbox->getName());
 			return $this->htmlBody = $this->driver->getBody($this->id, $this->htmlBodyIds);
-		} else {
-			return $this->htmlBody;
 		}
+
+		return $this->htmlBody;
 	}
 
 	/**
@@ -113,9 +130,9 @@ public function getTextBody()
 		if($this->textBody === NULL) {
 			$this->driver->switchMailbox($this->mailbox->getName());
 			return $this->textBody = $this->driver->getBody($this->id, $this->textBodyIds);
-		} else {
-			return $this->textBody;
 		}
+
+		return $this->textBody;
 	}
 
 	/**
@@ -133,6 +150,21 @@ public function getAttachments()
 		return $this->attachments;
 	}
 
+	/**
+	 * @return MimePart[]
+	 */
+	public function getMimeParts()
+	{
+		$this->driver->switchMailbox($this->mailbox->getName());
+		return $this->mimeParts;
+	}
+
+	/** @deprecated use getMimeParts() instead */
+	public function getParts() {
+		\trigger_error(\E_USER_DEPRECATED, 'use getMimeParts() instead');
+		return $this->getMimeParts();
+	}
+
 	protected function addStructurePart($structure, $partId)
 	{
 		$type = $structure->type;
@@ -151,13 +183,27 @@ protected function addStructurePart($structure, $partId)
 			}
 		}
 
+		/** @noinspection NestedTernaryOperatorInspection Yep, will fix this when we switch to PHP7 level; see ?? operator */
+		$this->mimeParts[] = new MimePart(
+			$this->driver, // for lazy loading
+			$this->id,
+			$partId,
+			self::$typeTable[$type]. '/' . $subtype,
+			(empty($parameters['filename']) ? $parameters['filename'] :  (
+				empty($parameters['name']) ? $parameters['name'] : ''
+			)),
+			$encoding
+		);
+
+
 		if(isset($parameters['filename']) || isset($parameters['name'])) {
 			$this->attachmentsIds[] = array(
 				'id' => $partId,
 				'encoding' => $encoding,
 				'name' => isset($parameters['filename']) ? $parameters['filename'] : $parameters['name'],
 				'type' => self::$typeTable[$type]. '/' . $subtype,
 			);
+
 		} else if($type === self::TYPE_TEXT) {
 			if($subtype === 'HTML') {
 				$this->htmlBodyIds[] = array('id' => $partId, 'encoding' => $encoding);

MailLibrary/loader.php

@@ -14,6 +14,7 @@
 		'greeny\maillibrary\contactlist' => 'ContactList.php',
 		'greeny\maillibrary\contact' => 'Contact.php',
 		'greeny\maillibrary\attachment' => 'Attachment.php',
+		'greeny\maillibrary\mimepart' => 'MimePart.php',
 		'greeny\maillibrary\structures\istructure' => 'Structures/IStructure.php',
 		'greeny\maillibrary\structures\imapstructure' => 'Structures/ImapStructure.php',
 		'greeny\maillibrary\drivers\idriver' => 'Drivers/IDriver.php',