Download the PHP package melloww/laravel-mailfiles without Composer
On this page you can find all versions of the php package melloww/laravel-mailfiles. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download melloww/laravel-mailfiles
More information about melloww/laravel-mailfiles
Files in melloww/laravel-mailfiles
Package laravel-mailfiles
Short Description Read .eml and .msg email files through one unified, framework-agnostic API. Pure PHP, no external mail-parsing libraries.
License MIT
Homepage https://github.com/melloww/laravel-mailfiles
Informations about the package laravel-mailfiles
Laravel MailFiles — one API for .eml and .msg
Read RFC 822 .eml files and Outlook .msg (MAPI) files through a single,
consistent, read-only API. Subject, sender, recipients, dates, text/HTML bodies and
attachments all come back the same way no matter which format you started with.
Why this package
To handle support for both the .eml and .msg format, I often found myself duck taping together several parsers for either format to read the email properly depending on whether it was a .eml from a Mac client or a .msg from an Outlook inbox on Windows. To streamline this process, this package can hopefully fill that need for others as well.
- One API, two formats. Both parsers emit the same immutable
Emailvalue object. - No external mail-parsing libraries. The
.msgreader is a from-scratch pure-PHP OLE2 / MAPI reader; the.emlreader is a from-scratch MIME parser. Neitherphp-mime-mail-parsernorhfig/mapiis pulled in. - No required PHP extension beyond
mbstring. Themailparseextension is optional — see EML drivers. - Framework-agnostic core. Works fine outside Laravel; the Laravel layer just adds a facade, container binding and an Artisan command.
Installation
The service provider and MailFiles facade are auto-discovered. Optionally publish
the config file:
Requires PHP 8.2+ and the mbstring extension (iconv is used as a fallback for
exotic charsets when present).
Reading a message
Format detection is based on file content (the OLE2 signature), not the extension, so a mislabelled file still reads correctly.
The unified API
Every accessor below works identically for .eml and .msg.
Envelope
| Method | Returns | Notes |
|---|---|---|
format() |
MailFormat enum |
MailFormat::Eml or MailFormat::Msg |
subject() |
?string |
RFC 2047 encoded-words decoded to UTF-8 |
from() |
?Address |
the author of the message |
sender() |
?Address |
the actual submitter; falls back to from() |
to() |
list<Address> |
|
cc() |
list<Address> |
|
bcc() |
list<Address> |
|
replyTo() |
list<Address> |
|
recipients() |
list<Address> |
To + Cc + Bcc combined |
date() |
?DateTimeImmutable |
when the message was sent |
messageId() |
?string |
without the surrounding < > |
Metadata
Beyond the envelope, richer metadata is first-class (and works for .msg too —
MAPI priority/sensitivity/threading properties are surfaced through the same API):
Bodies
| Method | Returns | Notes |
|---|---|---|
textBody() |
?string |
the text/plain part, UTF-8 |
htmlBody() |
?string |
the text/html part, UTF-8 |
body() |
?string |
text body, or the HTML stripped to text |
markdown() |
?string |
the HTML body converted to Markdown (or the text body) |
cleanHtml() |
?string |
HTML with scripts/styles/tags removed |
bodyAs(BodyFormat $f) |
?string |
the body as Html, Text or Markdown |
rtfBody() |
?string |
the decompressed RTF body (.msg only) |
hasTextBody() / hasHtmlBody() / hasRtfBody() |
bool |
For Outlook .msg files that carry only a compressed-RTF body, the reader
decompresses it (MS-OXRTFCP) and, when the RTF encapsulates HTML, de-encapsulates
that HTML into htmlBody(); otherwise it falls back to text. rtfBody() always
exposes the raw decompressed RTF.
The HTML→Markdown conversion is built in (no dependency); it uses the bundled
dom extension when available and degrades to plain text otherwise.
Attachments
| Method | Returns | Notes |
|---|---|---|
attachments() |
list<Attachment> |
genuine attachments only (no inline images) |
inlineAttachments() |
list<Attachment> |
embedded body images (logos, icons, pixels) |
allAttachments() |
list<Attachment> |
everything |
hasAttachments() |
bool |
true only when there are genuine attachments |
inlineAttachmentByContentId($cid) |
?Attachment |
resolve a cid: reference |
contentType() returns the type exactly as the message declared it (fast, and
null when omitted). mimeType() falls back to detecting the type from the
payload's magic bytes (via ext-fileinfo) — never from the file-name
extension, which is attacker-controlled and can lie. Use mimeType() when you
need a dependable type; note it resolves the content to sniff it.
Real attachments vs. inline/embedded images
A common headache with other libraries is that the four tiny social-media icons in a signature, an embedded logo or a tracking pixel all show up as "attachments", drowning out the one PDF the sender actually attached.
attachments() returns only the genuine ones. Each part is tagged with an
AttachmentDisposition (Attachment or Inline), decided from what the message
actually does rather than a single unreliable header:
- Is the part referenced by the body? If the HTML contains
cid:<its-id>(or its Content-Location), it is body content → Inline. This is the decisive signal, and it catches the notorious case where Outlook marks a body-referenced image asContent-Disposition: attachment. Content-Disposition: inline, or the MAPIATT_MHTML_REF/ hidden flags for.msg→ Inline.- Sits in a
multipart/relatedcontainer as an image → Inline. - Otherwise → a real Attachment (an unreferenced image with a stray Content-ID is still a file the sender attached).
Nested / embedded messages
When an attachment is itself an email — a .eml attached to a .eml, a .msg
embedded in a .msg, or one format inside the other — it is parsed recursively
into its own Email:
Recursion (and its depth limit) is configurable — see
Nested message options. It is bounded by max_depth
to stay safe against maliciously deep files.
Headers
For .msg files the headers bag is populated from the original transport headers
(PR_TRANSPORT_MESSAGE_HEADERS) when present, and otherwise synthesised from the
MAPI properties so Subject, From, To, Date and Message-ID are always there.
Address
Serialising
$email->toArray() returns a plain array of everything (minus attachment bytes),
handy for logging, JSON responses or persisting metadata.
Email threads (forwards & replies)
When a message forwards or replies to earlier ones, the chain can be reconstructed — including the different contacts at each hop.
Thread helpers: current() (the message itself), original() (the oldest
recovered message), hasHistory(), count(), isForwarded(), isReply().
How the chain is recovered, in order of reliability:
- Attached originals — a message forwarded as an attachment
(
message/rfc822or an embedded.msg) is parsed structurally, so its contacts are exact (ThreadEntryType::Attached). - Quoted "forwarded message" header blocks in the body — the
From:/To:/Cc:/Subject:lines are parsed, giving full per-item contacts (ThreadEntryType::Forwarded). - Reply attribution lines ("On … wrote:") — yield the quoted author
(
ThreadEntryType::Reply). - Forwarding headers —
X-Original-Sender,Resent-From,X-MS-Exchange-Organization-OriginalSender, etc., as a fallback.
Body-based recovery (2 & 3) is heuristic: it reads text a human wrote, so it copes with quirks like non-breaking spaces, Outlook HTML-table layouts and ~15 languages of labels/verbs — but it cannot be perfect. Prefer forwarded-as-attachment when accuracy is critical.
ThreadMessage::isReliable()tells you whether an entry came from a structural source (1) or a heuristic one.
Signed, encrypted & special parts
For signed messages the signed content is what you read through body() and
attachments() — the detached signature part is not surfaced as an attachment.
Calendar invitations (text/calendar) are parsed into events:
Automated messages are flagged too:
Mailboxes and batch reading
Read a whole Unix mbox spool (streaming — one message in memory at a time):
Or every .eml/.msg in a directory (keyed by path):
Memory & performance
- Attachment payloads and nested messages are resolved lazily: listing
attachments (names, types, content-ids, disposition) does not decode or hold
the bytes. Only the attachments you call
content(),size()orsaveTo()on are materialised — note thatsize()resolves the payload, because a MIME body's decoded length is not known from its headers..msgstreams are likewise read on demand. -
Header-only reads for indexing skip the body, attachments, calendar and nested messages entirely. For EML they read only the header block from disk (not the whole file):
mboxreading streams message-by-message.- The remaining whole-file load is the source file for a full
read()(file_get_contents), because MIME needs to scan boundaries and OLE2 needs random access. For a mailbox, preferMailFile::mbox(); for indexing, preferMailFile::headers(). A fully streaming single-message parser is not provided.
Scope & boundaries
In scope: reading .eml (RFC 822/MIME) and .msg (Outlook MAPI), mbox spools,
and directories. Deliberately out of scope:
- Writing/mutating messages — this package is read-only.
- PST/OST mailbox databases — use a dedicated extractor to split them into
.msg/.emlfirst, then read those here. - Decrypting S/MIME/PGP or verifying signatures — the package detects them and reads the signed content, but does no cryptography.
- Decoding the TNEF (winmail.dat) container — it is detected and its bytes exposed, but not unpacked.
Laravel usage
Artisan command
A small reference command prints a parsed summary of any file:
EML drivers
.eml parsing has two interchangeable drivers, configured in config/mailfiles.php:
native(default) — the bundled pure-PHP MIME parser. No extension required.mailparse— delegates structural parsing to the PHPmailparseextension. Decoding, charset handling and the public API are identical to the native driver.auto— usemailparsewhen the extension is loaded, otherwisenative.
.msg files are always read by the bundled native MAPI reader.
Nested message options
Recursive extraction of messages-within-messages is on by default and tunable in
config/mailfiles.php:
Outside Laravel, pass a ParseOptions to the reader:
How it works
.eml— a recursive RFC 822 / MIME parser: header unfolding, RFC 2047 encoded-words, RFC 2231 parameter continuations, nestedmultipart/*trees, quoted-printable / base64 / uuencode transfer decoding and charset conversion to UTF-8..msg— a read-only OLE2 / Compound File reader (MS-CFB: FAT, mini-FAT and the directory tree) feeding a MAPI property decoder (MS-OXMSG / MS-OXPROPS) that understands the__substg1.0_*streams, the__properties_version1.0table, and the__recip_*/__attach_*storages.
Replacing php-mime-mail-parser + hfig/mapi
| Previously | Now |
|---|---|
(new Parser)->setText($eml)->getSubject() |
MailFile::read($path)->subject() |
$parser->getHeader('from') |
$email->from() / $email->header('from') |
$parser->getTo() |
$email->to() |
$parser->getMessageBody('text') |
$email->textBody() |
$parser->getMessageBody('html') |
$email->htmlBody() |
$parser->getAttachments() |
$email->attachments() |
$messageFactory->parseMessage($doc)->getProperties()['subject'] |
$email->subject() |
$msg->getAttachments()[0]->getContent() |
$email->attachments()[0]->content() |
Testing
The test suite runs against real .eml and .msg fixtures in tests/Fixtures.
License
The MIT License (MIT). Please see License File for more information.
All versions of laravel-mailfiles with dependencies
ext-mbstring Version *
spatie/laravel-package-tools Version ^1.16
illuminate/contracts Version ^10.0||^11.0||^12.0||^13.0