ImapEngine

ImapEngine is a native PHP implementation of the IMAP protocol for reading, searching, and managing mailboxes, folders, and messages over raw sockets. It replaces the compiled ext-imap PHP extension entirely, so it runs on shared hosting, serverless platforms, and slim container images where enabling that extension isn’t practical or possible.

On top of a hand-rolled RFC 9051 command/response layer, it exposes a fluent, chainable query API for searching and fetching messages, first-class MIME parsing for message bodies and attachments, and IMAP IDLE support for real-time new-mail notifications. Its connection layer is built around interfaces and an injectable stream abstraction, which lets the test suite script exact server responses for fast unit tests while a separate integration suite runs the same code against a real Dockerized IMAP server in CI.

What You Get

• A Mailbox facade for connecting, authenticating (plain or OAuth), and managing folder selection state
• A fluent MessageQuery / ImapQueryBuilder API for building IMAP SEARCH and SORT queries and paginating results
• Full MIME parsing of fetched messages into Message, Attachment, and Address objects via zbateson/mail-mime-parser
• Idle and Poll classes for real-time and polling-based new-message notification, with automatic reconnect on server timeouts
• A typed exception hierarchy (ImapCommandException, ImapConnectionTimedOutException, ImapConnectionClosedException, etc.) for distinguishing failure modes
• A FakeStream/ConnectionInterface testing abstraction so consuming applications can script IMAP responses without a live server

Common Use Cases

• Reading and processing incoming support or transactional email inside a PHP or Laravel application without enabling ext-imap
• Building a webmail client or mail-triage tool that needs fluent search across folders and mailboxes
• Watching a mailbox for new messages in near real time using IDLE, e.g. for an email-to-ticket pipeline
• Running on hosts (shared hosting, serverless functions, minimal Docker images) where the ext-imap extension can’t be installed
• Parsing multipart MIME messages and extracting attachments from archived or forwarded email

Under The Hood

Architecture ImapEngine implements a layered architecture separating protocol mechanics from the developer-facing API: at the base, ImapConnection drives the raw RFC 9051 IMAP wire protocol directly over an ImapStream socket, tagging commands with an incrementing sequence counter and parsing multi-line tagged/untagged responses through a token/response pipeline rather than PHP’s ext-imap. Mailbox sits above it as the facade, owning config, capability caching, and folder-selection state, and lazily instantiates a connection (or accepts an injected ConnectionInterface, notably a fake stream for tests) on first use. FolderRepository/Folder wrap folder listing and selection, while MessageQuery — composing a query-builder trait — provides a fluent, chainable search/fetch DSL that lazily executes SEARCH/SORT/FETCH commands and hydrates results into Message objects via a dedicated message parser. Idle/Poll layer real-time change detection on top of the same connection. Dependency injection at the connection boundary is what makes response-scripted unit tests possible without a live IMAP server, and interfaces decouple the trait-heavy concrete classes from consumers; a change to the core token/response parsing would ripple through every higher layer that consumes that same response stream.

Tech Stack ImapEngine targets PHP 8.1+ and depends on symfony/mime for MIME construction, nesbot/carbon for timestamp handling, illuminate/collections (Laravel’s standalone Collection package) used throughout for typed collections, zbateson/mail-mime-parser for parsing fetched message bodies, and egulias/email-validator for RFC-compliant address validation. Dev tooling is Pest for testing, PHPStan for static analysis, and Laravel Pint for code style, auto-committed via a dedicated CI workflow; integration tests run against a real Dockerized IMAP server rather than mocks alone. It has no hard framework dependency beyond the Illuminate Collections package, distributed purely via Packagist with PSR-4 autoloading.

Code Quality The suite is split cleanly into fast unit tests that script exact server responses against a fake stream, and integration tests that run against a live IMAP server both locally via Docker Compose and in CI on every push and a daily schedule. Error handling is explicit and typed via a dedicated exceptions namespace mapping distinct IMAP failure modes to specific catchable classes, with the one intentional exception-suppression point during connection teardown called out in a comment rather than silently swallowed elsewhere. Naming is consistent and enforced by an automated style-fix workflow, nearly every public method carries a documentation block, and static analysis runs on every change.

API Design The public surface favors a small number of composable entry points — Mailbox::make(), fluent query methods, and folder/message objects with consistent accessor traits — over a wide flat API, so common tasks like searching a folder or listening for new mail read as a short method chain. Documentation lives on a dedicated docs site rather than solely in the README, and the interface-driven design (MailboxInterface, FolderInterface, MessageQueryInterface) gives consumers a clear seam for mocking IMAP interactions in their own application tests, at the cost of needing to look past the README to that external documentation for full usage guidance.