Skip to content

Separate protocol package within the existing repository #196

Open

Description

@bago

Hi,

Would you consider exposing ImapEngine’s low-level IMAP client as a separate Composer package, maintained in the same repository?

I use ImapEngine in a PHP mail fetcher that already has its own processing pipeline and MIME parser. It needs connection/authentication, folder listing, UID searches, raw message retrieval, flags, moves and expunge, but does not use the higher-level message API, composition, date handling or pagination.

Currently, installing ImapEngine also brings in dependencies for those features, including Carbon and Symfony Mime.

As an experiment, I extracted the protocol layer from v1.25.8 into a local package, without rewriting the protocol implementation. The subset contains around 50 source files and still uses Illuminate Collections. In our application, this reduced the vendor directory from approximately 9.2 MiB to 4.6 MiB.

The extracted code passes our offline protocol tests, including XOAUTH2, UID handling, binary literals, raw message retrieval, PEEK, mutation failures and logout without implicit expunge. A live Outlook dry run also succeeded, with message flags checked before and after retrieval.

My proposal would be:

  • Add a package such as directorytree/imapengine-protocol containing the connection, command encoder, tokenizer/parser, responses, streams and related types.
  • Keep directorytree/imapengine as the full library, depending on the protocol package and its existing higher-level dependencies.
  • Maintain both packages in this repository, with automated publishing of the protocol package.
  • Preserve the existing namespaces and public APIs, so applications installing the full library would not need to change their code.
  • Run the protocol tests with only the minimal dependencies installed, alongside the full library’s test suite.

The intent is to avoid a separately maintained fork while preserving the current installation experience for users of the complete library.

This would require some changes to package layout and release automation, so I wanted to discuss the direction before preparing a PR. Would this separation fit the project, and is there a repository/package layout you would prefer?

Activity

  1. stevebauman commented on Nov 4, 2026

    @stevebauman
    Member

    Hey @bago! I don't think I'm particularly against it. directorytree/imapengine-client would likely be my preference for naming.

    Though this will be a major breaking change. I wouldn't want to split the packages up and have them both adhere to the same namespaces just to avoid it. I'd prefer to adopt the typical Vendor\Package convention like all my other packages in this org.

    Luckily I haven't merged v2.0 yet which is nearly complete and going through missed bug fixes. Let me think about this though, as I don't have a need for this right now, but I do understand having this separated would likely benefit the package regardless (for myself and consumers).

  2. bago commented on Nov 4, 2026

    @bago
    Author

    I didn't see the v2.0 PR before, cool! Let me know if I can do anything to help.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions