README

Testable and PSR-compliant mail mime parser alternative to PHP's imap* functions and Pear libraries for reading messages in Internet Message Format RFC 822 (and later revisions RFC 2822, RFC 5322).

The goals of this project are to be:

• Well written
• Standards-compliant but forgiving
• Tested where possible

To include it for use in your project, install it via composer:

composer require zbateson/mail-mime-parser

Sponsors

A huge thank you to all my sponsors. <3

If this project's helped you, please consider sponsoring me.

New in 4.0

Version 4.0 requires PHP 8.1+ and focuses on API cleanup and improved configurability. For details, see the 4.0 Upgrade Guide.

Requirements

MailMimeParser requires PHP 8.1 or newer. Tested on PHP 8.1, 8.2, 8.3, 8.4 and 8.5.

Usage

use ZBateson\MailMimeParser\MailMimeParser;
use ZBateson\MailMimeParser\Message;
use ZBateson\MailMimeParser\Header\HeaderConsts;

// use an instance of MailMimeParser as a class dependency
$mailParser = new MailMimeParser();

// parse() accepts a string, resource or Psr7 StreamInterface
// pass `true` as the second argument to attach the passed $handle and close
// it when the returned IMessage is destroyed.
$handle = fopen('file.mime', 'r');
$message = $mailParser->parse($handle, false);         // returns `IMessage`

// OR: use this procedurally (Message::from also accepts a string,
// resource or Psr7 StreamInterface
// true or false as second parameter doesn't matter if passing a string.
$string = "Content-Type: text/plain\r\nSubject: Test\r\n\r\nMessage";
$message = Message::from($string, false);

echo $message->getHeaderValue(HeaderConsts::FROM);     // user@example.com
echo $message
    ->getHeader(HeaderConsts::FROM)                    // AddressHeader
    ->getPersonName();                                 // Person Name
echo $message->getSubject();                           // The email's subject
echo $message
    ->getHeader(HeaderConsts::TO)                      // also AddressHeader
    ->getAddresses()[0]                                // AddressPart
    ->getPersonName();                                 // Person Name
echo $message
    ->getHeader(HeaderConsts::CC)                      // also AddressHeader
    ->getAddresses()[0]                                // AddressPart
    ->getEmail();                                      // user@example.com

echo $message->getTextContent();                       // or getHtmlContent()

echo $message->getHeader('X-Foo');                     // for custom or undocumented headers

$att = $message->getAttachmentPart(0);                 // first attachment
echo $att->getHeaderValue(HeaderConsts::CONTENT_TYPE); // e.g. "text/plain"
echo $att->getHeaderParameter(                         // value of "charset" part
    HeaderConsts::CONTENT_TYPE,
    'charset'
);
echo $att->getContent();                               // get the attached file's contents
$stream = $att->getContentStream();                    // the file is decoded automatically
$dest = \GuzzleHttp\Psr7\stream_for(
    fopen('my-file.ext')
);
\GuzzleHttp\Psr7\copy_to_stream(
    $stream, $dest
);
// OR: more simply if saving or copying to another stream
$att->saveContent('my-file.ext');               // writes to my-file.ext
$att->saveContent($stream);                     // copies to the stream

// close only when $message is no longer being used.
fclose($handle);

Encryption and Signing Plugins

Optional companion packages add S/MIME and PGP/MIME support for decrypting, encrypting, signing and verifying messages:

• zbateson/mmp-crypt-smime -- S/MIME via PHP's OpenSSL extension
• zbateson/mmp-crypt-gpg -- PGP/MIME via PEAR's Crypt_GPG

Install either package and encrypted/signed messages are automatically detected and decrypted during parsing. See the Usage Guide for examples of reading encrypted messages and composing signed/encrypted ones.

Documentation

• Usage Guide
• API Reference

Upgrade guides

• 1.x Upgrade Guide
• 2.x Upgrade Guide
• 3.x Upgrade Guide
• 4.x Upgrade Guide

License

BSD licensed - please see license agreement.