ImapEngine: IMAP in PHP without the IMAP extension

The problem is the extension, not the protocol

ImapEngine is a PHP library for managing IMAP mailboxes without the IMAP extension, and that single constraint explains almost every design decision in it.

IMAP in PHP normally means the ext-imap extension, which is a C extension that has to be compiled and linked into the interpreter. On a managed host or a restricted container, that is often not available, and even when it is, its API is the one PHP inherited from the old c-client library, with a mailbox stream handle and functions that mutate a selected folder in place. The library therefore implements the protocol in PHP, over a socket, so that mailbox management works anywhere PHP runs.

The audience is therefore narrow and well defined. Anyone building a support tool, a ticket intake system, a synchroniser or an archiving script who has hit the wall of a missing extension. It is not a general purpose mail client library, and it is not trying to be one.

The project ships as a Composer package, directorytree/imapengine, published on Packagist, with the source under src, a test suite under tests, and an art directory for the logo. The licence file is named license.md rather than LICENSE, which is a small detail but is the file to read, since the licence is MIT.

Installing with Composer, and where the documentation lives

The installation section is one command:

composer require directorytree/imapengine

That is the whole install step. There is no service to register, no extension to enable and no configuration file to write before you can use it, which is the point of a library that has to work on a host you do not control.

The documentation is a separate site, imapengine.com, which the README links both from the header and from the documentation section, where it says the site covers mailbox configuration, querying messages and managing folders. That is a compact statement of the feature surface: connect to a mailbox, query it, and organise it into folders.

For Laravel applications the README points at a separate repository, ImapEngine-Laravel, rather than trying to make the base package aware of a framework. The split is sensible. The base package is a protocol library, and the integration package is the part that knows about service providers, configuration files and queued jobs, and that part will have a lifecycle of its own.

The tests are configured in phpunit.xml and static analysis in phpstan.neon, so the package carries the tooling of a maintained library rather than a script collection, and the CI badge points at a workflow named run-tests.yml on the master branch.

The primary language is PHP and the default branch is master, with the last push on 2026-10-08 and recent releases v1.25.6 from 2026-08-24, v1.25.5 from 2026-08-10 and v1.25.4 from 2026-07-30, so the 1.25 line is moving every few weeks.

Greenmail is what the test suite talks to

The docker-compose file in the repository is small and it is about testing rather than deployment. It defines a single service, greenmail, on the greenmail/standalone:latest image, with a set of Greenmail options passed through the environment:

services:
    greenmail:
        image: greenmail/standalone:latest
        environment:
            - GREENMAIL_OPTS=-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.auth.disabled -Dgreenmail.verbose
        ports:
            - "3143:3143"

The options are worth reading. The setup.test.all option preloads test accounts, the hostname is set to 0.0.0.0 so the container is reachable from outside, auth is disabled so the test suite does not have to authenticate, and verbose turns on logging. Port 3143 is the plain IMAP port, published to the host so the tests can reach it.

This is the right way to test an IMAP client. A library that reimplements a protocol is easy to get wrong in exactly the ways a mock server would hide, because the mock would implement the behaviour the library expects. Greenmail is a real IMAP server, so the tests exercise the actual protocol, including the parts of it that are awkward, such as the state a message is in and the commands needed to move it between folders.

The trade-off is that the test environment needs a container runtime, and the Greenmail configuration here is deliberately permissive, with authentication off. That is fine for a test suite on a developer machine and is not something to copy into a staging environment that talks to a real mail server.

What the README does not tell you

The documentation section is where the project is honest about its own limits, and the gaps are worth naming before you commit.

There is no example of connecting to a mailbox, no listing of the supported commands, no configuration reference, and no note of which PHP versions or which IMAP extensions the library expects. The README says the documentation site covers mailbox configuration, querying messages and managing folders, so the detail is presumably there, but a reader of the repository alone is left with the shape of the API rather than its surface.

The same applies to the failure modes. IMAP has a handful of well known sharp edges, among them servers that require an ID command before login, servers that use implicit TLS on port 993 rather than STARTTLS, and the difference between a message being flagged, deleted and expunged, which is a three step operation rather than a single one. Whether the library handles those, and how it reports them, is not described in the README.

There is also no rollback or upgrade guidance in the README, and no changelog in the tree listing, even though the release tags move every few weeks. For a library with a stable 1.x version line that is a reasonable amount of churn, but it does mean the upgrade notes live in the releases rather than in the repository.

None of this makes the project a poor choice. It makes it one where you should read the documentation site and the release notes before you commit, rather than the other way round.

How it compares to the extension it replaces

The alternative here is not really a competing library, it is the platform's own IMAP extension, and the difference is worth understanding rather than dismissing.

The extension does the protocol work in C, inside the PHP process, which means the parsing and the string handling are done in the language's own memory model and the I/O is a stream the extension manages. It is the better implementation on every axis that matters for throughput and correctness, and it is what PHP's own documentation points you at. Its availability is the problem, and that problem is real: shared hosting providers have historically shipped it in a limited or disabled form, and container images that minimise their PHP build often omit it.

ImapEngine takes the opposite approach. The protocol is implemented in PHP, which means the library runs anywhere PHP runs, and it means the same code path is exercised on every host, so behaviour does not change with the environment.

There is a second difference that is about the API rather than the implementation. The extension works with a selected folder in a mutable stream, and you call functions like select, search, fetch and store on it. A library built for a modern application tends to expose the mailbox as an object with methods, which reads better in application code and plays better with a dependency injection container, and the Laravel integration package exists precisely to make that shape idiomatic in a framework.

So the trade is the native speed and maturity of the extension against portability and a modern object API, and the decision hinges on whether you control the host.

A small tree, a steady release line and a custom licence

The repository is compact, and that is a good sign for a focused library. At the top level there is composer.json, phpstan.neon, phpunit.xml, the docker-compose.yml, an art directory with the logo, a license.md file, a readme.md, and the src and tests directories. There is no framework, no config directory and no documentation directory in the tree, because the documentation is a website.

The release cadence is regular and the line is stable. The tags are v1.25.6 on 2026-08-24, v1.25.5 on 2026-08-10 and v1.25.4 on 2026-07-30, which is a patch release roughly every two weeks, and the last push to the repository was on 2026-10-08, so the branch is ahead of the newest tag. The homepage recorded in the repository metadata is imapengine.com, and the Packagist page for directorytree/imapengine is linked from the badges.

The licence is the one item to check carefully. The licence is MIT, and the file in the repository is license.md. For a library whose whole point is to be embedded in an application, the terms of that file are what your legal team will want to see, and the README does not summarise them.

The project is maintained by DirectoryTree, and the same organisation publishes the Laravel integration and a set of related packages under the same namespace. If you use the Laravel integration, the two version lines have to be compatible, and the README does not state a version constraint between them, which is the sort of thing to confirm when you pin your dependencies.

Editorial conclusion

Adopt ImapEngine if you need to read or move mail from PHP on a host where the IMAP extension is unavailable or refused, which is the exact problem the library exists to solve. Do not adopt it if the extension is present and working, since the native extension is the better implementation, and do not expect it to replace a full mail client, since it is a protocol library and not an end user interface. Verify first which PHP version and extensions the package expects, whether the account you connect to requires an implicit TLS port, and how the library handles folders and message state, because those are the parts the README leaves to the documentation rather than describing.

Frequently asked questions

Official sources

1. DirectoryTree/ImapEngine on GitHub
2. License: MIT
3. Project website
4. README
5. Releases