Imapengine Laravel Package

Product Decisions This Supports

• Build vs. buy for protocol plumbing. IMAP is a stateful, byte-oriented protocol where the product risk lives in edge cases — 8-bit response bytes, literal continuation handling, RFC 2231 MIME parameter decoding, multi-line response parsing, tokenizer OOM on malformed input, and attachment re-read corruption. Every one of those shows up in this package's changelog as a fixed item. Buying an MIT-licensed client at ~$0 license cost and redirecting engineering to inbox UX, rules, and sync semantics is almost always the right trade. What you still own: persistence model, attachment storage, credential handling, queueing/retries, and observability.
• Dropping ext-imap as a platform constraint. The library is native PHP and works standalone or with Laravel, so it unblocks hosting environments where the legacy extension is unavailable, deprecated, or blocked by security policy — a decision that otherwise surfaces late as an infrastructure blocker.
• Feature viability and scoping. The capability surface maps directly onto common email bets: fluent query builder (subject/sender/date/flags/size), folder management, move/copy/flag/delete, lazy-loaded headers, bodies, and attachments, bodyStructure, server-side SORT, bulk operations, poll()/idle() with timeout callback, mailbox quotas, UID sequence ranges, and Message-ID/RFC822.SIZE helpers. That is enough to prototype a shared team inbox, mailbox sync/archival, an attachment ingestion pipeline, or "connect your mailbox" in days rather than quarters.
• Performance and cost positioning. Lazy loading (v1.23–1.24) keeps memory flat for list views and avoids paying for full-body fetches until a user opens a message. Server-side SORT and LARGER/SMALLER push filtering to the mail server instead of transferring and filtering in PHP. Single-request message fetching (v1.17.0) and sequence-range payload optimization (v1.25.6) cut round trips — meaningful when polling many mailboxes under per-connection or per-latency cost.
• Differentiation and monetization levers. If email is a core workflow surface, this underpins premium features: team inboxes, automation rules and routing, provider migration tooling, compliance/legal-hold export (aided by Message-ID, In-Reply-To, RFC822.SIZE, Content-Disposition), and near-real-time notification via idle()/poll() without standing up a full push pipeline. If email is a commodity notification channel for your product, this is over-investment — use a transactional sender instead.
• Roadmap sequencing signal. The release cadence shows where the maintainer invests: correctness and security fixes (ID command parameter escaping for injection prevention in v1.22.3, safe token reads, stream-socket error handling, UTF-8 address decoding, PHPStan levels 1–4) alongside capability additions. A steady stream of defensive fixes is a good sign for a library in your critical path — and also a reason to pin versions and re-test on upgrade rather than float.
• Architecture decision: keep it at the edge. Commit now to wrapping the library behind an internal MailService interface so DirectoryTree\ImapEngine\* types don't leak into your domain. That preserves the option to swap to Gmail API or Microsoft Graph later without touching product code, and it makes the "0 Packagist dependents" risk cheap to absorb.

When to Consider This Package

Consider adoption when:

• The requirement is to read, query, and manage IMAP mailboxes — not merely send transactional email.
• You're on PHP/Laravel and want an expressive, framework-agnostic, testable client instead of raw imap_* calls or hand-rolled protocol work.
• ext-imap is unavailable, deprecated in your stack, or blocked by hosting/security policy.
• The roadmap includes behaviors that are expensive to build yourself: lazy header/body loading, bulk flag/move/delete, server-side sort, size-based search, long-polling for new mail, quota checks, UID-range sync.
• Correctness and security review matters: injection escaping, safe token reads, connection-failure exceptions, and MIME decoding are bugs you would otherwise discover in production.
• Email is a core workflow surface or differentiator, so the integration and operational investment is justified.

Look elsewhere when:

• You primarily need sending (password resets, receipts, notifications). Use your mailer or a managed transactional API; do not adopt an IMAP client for this.
• You can standardize on Gmail API or Microsoft Graph — provider APIs give you push notifications, richer metadata, and OAuth semantics that generic IMAP only approximates.
• You need an enterprise SLA, paid support, vendor indemnity, or turnkey attachment storage. This is a community package; storage, persistence, and support are yours to build.
• The use case is genuinely small and ext-imap is present and sufficient — the abstraction isn't worth the added dependency.
• Your risk policy can't tolerate a niche package with a thin public dependent footprint. If you adopt anyway, mitigate: pin exact versions, write integration tests against every target provider (Gmail, Outlook/M365, Dovecot, Exchange), maintain an internal adapter, and monitor upstream releases for security notes.

How to Pitch It (Stakeholders)

One-liner for executives: We can ship mailbox-reading features — shared inboxes, search, attachment handling, near-real-time new-mail notifications — on top of a mature MIT-licensed PHP library instead of funding a quarter of protocol engineering, at zero license cost and with an exit path preserved.

For engineering: It's a modern, actively maintained native-PHP IMAP client with a fluent API, Laravel integration, and no ext-imap dependency. It already covers the hard parts we'd get wrong: lazy header/body/attachment loading, bulk operations, server-side SORT and size criteria, idle()/poll(), quotas, bodyStructure, and UID handling. Security-relevant fixes are landing regularly (command-injection escaping, safe token reads, socket error handling, MIME/RFC 2231 decoding, PHPStan 1–4). The trade: ~583 stars and no public dependents, so we pin versions, test against our target providers in CI, and keep the library behind an internal MailService interface.

The ask: Approve a small spike (one engineer, ~1–2 weeks) to build the adapter plus integration tests against Gmail, M365, and Dovecot. Success criteria: message list, search, attachment download, and new-mail polling working end-to-end through our interface, with no library types in the domain layer.

What we are explicitly not buying: SLA, support, attachment storage, or a sync engine. Those remain ours — and that's the honest cost of this decision.