Mail Mime Parser Laravel Package

Product Decisions This Supports

Build vs. buy for any email-ingestion feature. This package answers the "parse" half of every inbound-email roadmap item. It is a well-scoped buy that removes the nastiest 20% of the work (RFC 2045/2047 encoded words, RFC 2231 split parameters, nested multipart boundaries, transfer-encoding decoding, charset handling) while leaving the parts you should own (transport, storage, routing, business logic) in your codebase.

• Inbound email as a product surface. Reply-by-email on threads, "email-to-ticket" support desks, CRM activity logging, forwarding an invoice/receipt into an expense flow, or letting a user email a document into your app — all of these need reliable MIME decomposition before any product logic runs. This package is the decomposition layer.
• Extracting structured signal from unstructured mail. Sender/recipient identity (AddressHeader::getAddresses(), getPersonName()), subject, X- custom headers, text vs. HTML bodies, and attachments with filenames and decoded content streams. That maps directly to a data model: sender, subject, body_text, body_html, attachments[].
• Attachment pipelines. getAttachmentPart(n), getContentStream(), and saveContent($path) mean attachments can be streamed straight to S3 or local disk without buffering whole files in memory — a concrete cost and reliability decision, not just a convenience.
• Compliance and regulated mail (roadmap). Optional companion packages (mmp-crypt-smime, mmp-crypt-gpg) let the parser auto-detect and decrypt S/MIME or PGP/MIME. If you're selling into healthcare, legal, or finance, "we can ingest signed/encrypted mail" is a roadmap item you can scope as configuration rather than a quarter of engineering.
• Make vs. buy for the parser itself. The realistic alternatives are PHP's imap_* functions (procedural, hard to unit test, requires the IMAP extension, awkward to feed a stored string), PEAR Mail_mime (dated), or hand-rolling regexes against boundary= (a recurring source of production incidents). Choosing this package is a defensible "don't roll your own parser" decision.
• Platform constraint decisions. v4 requires PHP 8.1+, which is a forcing function for your Laravel upgrade plan. PSR-7 StreamInterface support and PSR-4/PSR-compliant DI mean it slots into a modern Laravel container instead of fighting it.
• Testability as a design goal. parse() accepts a raw string, so fixtures are just .eml files in your test suite. That directly supports CI-level regression coverage for the "customer sent us a weird email" class of bug.
• Security posture of a dependency (a decision, not a footnote). The 3.0.6 / 4.0.2 / 4.0.6 releases fixed CRLF header injection and multiple unbounded-resource-consumption issues, and added configurable caps (maxMimePartCount, maxMimePartDepth, maxHeaderCount, maxMessageHeaderCount, maxMessageHeaderSizeBytes, maxMessageHeaderTokenCount). If you accept mail from untrusted senders, you must pin a patched version and tune those limits — that's a real backlog item, not a formality.

When to Consider This Package

Adopt when:

• You need to parse RFC 822/2822/5322 messages in PHP and you control the transport separately (IMAP fetch via webklex/php-imap, a webhook from Postmark/Mailgun/SES, an .eml file, or a raw request body).
• Your messages are real-world messy — multipart/alternative, nested multipart/mixed, base64/QP encodings, non-UTF-8 charsets, RFC 2047 encoded subjects, long attachment filenames. This is precisely where hand-rolled parsing fails and a standards-compliant-but-forgiving parser earns its keep.
• You want attachments streamed, not slurped into memory, and you need decoded content without writing your own transfer-encoding logic.
• You need S/MIME or PGP/MIME and are willing to add a companion package.
• Your team values PSR compliance and injectable dependencies over a batteries-included framework integration — you're comfortable writing a small MailParserService wrapper and binding it in a service provider.
• You're on PHP 8.1+ and can commit to tracking patch releases, since the recent CVE history means version drift is a genuine risk.

Look elsewhere, or scope it down, when:

• You need sending, not just receiving. This is a parser. Composing and delivering mail is Symfony Mailer / Laravel's Mail facade. Don't expect it to replace them.
• You need mailbox management — listing folders, flagging, moving, searching server-side. That's an IMAP client's job; the README positions itself as an alternative to the imap_* reading functions, not to a full IMAP library.
• You want a first-party Laravel package. There's no service provider, no facade, no config file published into config/. Expect to write that glue — a day of work, not a blocker, but budget it honestly.
• Your volume is extreme and you're memory-bound. Parsing is CPU-and-memory work; the configurable limits protect you but also mean tuning per workload. If you're at millions of messages, evaluate a queue-per-message design before adopting, and consider whether a dedicated mail-infrastructure service is cheaper than your engineers' time.
• You're on PHP < 8.1 and can't upgrade. Stay on the 3.x line only if you've verified the security fixes landed there (3.0.6 did), and treat it as technical debt with a date on it.
• Ecosystem weight matters to your risk committee. 552 stars, BSD-2-Clause, and a single primary maintainer (with a sponsor-funded model) is a bus-factor conversation. It is not a reason to reject — the license is permissive and the code is yours to fork — but it is a reason to write the wrapper so the dependency is swappable.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: Inbound email is a feature request we keep deferring because "parsing email properly" sounds like a bottomless pit. It isn't, if we buy the parsing layer instead of building it. zbateson/mail-mime-parser is a mature, permissively licensed (BSD-2-Clause) PHP library that turns a raw email into structured fields — sender, subject, body, attachments — including the ugly real-world cases that break naive implementations. It is actively maintained (recent releases with security hardening), free, and has no lock-in: the BSD license means we can fork it if we ever need to. Adopting it converts a multi-sprint infrastructure risk into a two-week feature delivery.

For engineering — why this is the right dependency:

• Scope discipline. It parses. It does not fetch, store, route, or send. Our transport choice stays ours, which is the boundary we actually want to own.
• Testable by construction. parse($string) and Message::from($string) mean fixtures are .eml files, not mocks of a mail server. Our test suite gets better, not worse.
• PSR-compliant and DI-driven. Constructor injection, PSR-7 streams in and out, PSR-4/PSR-3 logging. It composes with the Laravel container cleanly; a thin MailParserService plus a service-provider binding is the entire integration.
• Streaming attachments. getContentStream() / saveContent() avoids loading large attachments into memory — a direct win on worker memory ceilings.
• Hardened limits are configurable, and we must configure them. Recent CVEs were header injection and resource exhaustion; the fixes ship as caps on part count, nesting depth, header count, header bytes, and header tokens. Action item: pin ^4.0.6 or later, override the defaults via DI config for our expected message sizes, run untrusted input through a queue with a timeout, and never construct messages from unvalidated user input.

For the business — what it unlocks and what it costs:

• Unlocks: email-to-ticket, reply-by-email threading, document intake by email, CRM activity capture, and (later) ingestion of signed/encrypted mail via the S/MIME and PGP companion packages.
• Costs: zero license spend; roughly one to two engineer-weeks to integrate, wrap, and test in a Laravel app, plus an ongoing obligation to track patch releases.
• Risks to accept knowingly: single-primary-maintainer dependency (mitigated by BSD license and a swappable wrapper interface), a PHP 8.1+ floor (aligns with our upgrade path), and a security-sensitive input surface that demands queue isolation, size limits, and prompt patching.

Recommendation: Adopt for the parsing layer of the next email-ingestion feature. Do not adopt it as a mail-sending or mailbox-management solution. Wrap it behind an internal interface so the choice remains reversible.