Uses UID-only search for mailbox discovery

[bramato]

Summary of changes

• Improves mailbox UID discovery by using a UID-only search path instead of loading per-message metadata
• Switches the discovery flow to operate on a UID sequence and rely on a UID-based search to collect UIDs
• Avoids fetching message flags and RFC822 headers during discovery, preventing unnecessary bandwidth, memory use, and potential server command-length issues on large mailboxes
• Adds regression test verifying that large UID sets (e.g., 5,000 UIDs) are discovered without invoking fetch-related metadata calls

What and why

• Previously, discovery used get() which retrieved metadata (flags, headers) for every match, then discarded it. This caused inefficiency and could fail on servers with command-length limits.
• The new approach uses UID-only search to return only identifiers, preserving existing normalization and ordering logic while being robust for large mailboxes.

Tests

• Adds a unit test confirming that searchUids() uses UID-only search, does not call setFetchBody(), and does not call get(), even for large UID lists.

Dependency and compatibility

• Bumps minimum webklex/php-imap requirement to ^6.2 to enable the UID-only search capability (Query::search()).
• No API changes for consumers beyond the dependency upgrade; existing public API remains intact.

Changelog

• Update includes 1.5.4 notes detailing the UID-only discovery fix and compatibility considerations.

Breaking Changes

• Requires webklex/php-imap ^6.2; environments using older versions must upgrade to utilize UID-only discovery.

Review Focus

• Correctness and completeness of the UID-only discovery path
• Absence of unnecessary metadata fetch during discovery (flags/headers)
• Coverage for large UID sets and out-of-order scenarios
• Impact and migration steps for the dependency upgrade to 6.2

[Copilot]

Pull request overview

This PR optimizes IMAP mailbox discovery by switching WebklexImapClient::searchUids() to a UID-only search path, avoiding per-message metadata fetches (flags/headers) and improving robustness/performance on large mailboxes and servers with command-length limits.

Changes:

• Update UID discovery to use setSequence(IMAP::ST_UID) + Query::search() instead of get() (avoids metadata fetch during discovery).
• Configure the Webklex client to fetch body-only content (rfc => BODY) for better server interoperability.
• Add/adjust unit tests and bump webklex/php-imap requirement to ^6.2, plus document the change in the changelog.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/Imap/WebklexImapClient.php	Switches discovery to UID-only search and preserves filtering/sorting behavior.
tests/Unit/WebklexImapClientTest.php	Adds regression coverage ensuring discovery uses UID-only search and avoids metadata fetch calls.
src/Imap/ImapClientFactory.php	Sets Webklex rfc option to BODY to fetch body-only content.
tests/Unit/ImapClientFactoryTest.php	Adds regression test asserting the factory configures body-only fetch mode.
composer.json	Bumps webklex/php-imap minimum requirement to ^6.2.
CHANGELOG.md	Documents the UID discovery fix, body-only fetch mode, and compatibility notes for 1.5.4.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.