api/Mail: tokenise search input to align with EGroupware syntax

[CActor]

Summary

Aligns the Mail module search-box behaviour with the documented EGroupware search syntax used in Addressbook / Calendar / InfoLog. Multi-word queries now match messages whose terms can appear in any order and with arbitrary text between them.

Problem this solves

Documented in detail in the forum thread (linked below). The Mail search field is the only one in EGroupware that forwards the entire input string to the IMAP server as a single substring match. A query like invoice overdue becomes SEARCH TEXT "invoice overdue", so a message body saying "the invoice from 02/2026 is overdue" is not matched, even though both words are clearly present.

Even with fts_flatcurve enabled on Dovecot, the phrase is matched as a contiguous bigram of tokens, so non-adjacent words remain a hard miss.

Solution

Two new protected static helpers added to Mail class:

• buildTokenizedSearch($string, callable $factory): ?Horde_Imap_Client_Search_Query
• parseSearchTokens($string): array

The relevant case branches (SUBJECT, FROM, TO, CC, BCC, BODY, TEXT) in createIMAPFilter() now tokenise the input and call the factory for each token, then combine the sub-queries with Horde_Imap_Client_Search_Query::andSearch() / orSearch() / negation according to the EGroupware-standard operator on each token.

User-facing syntax (matches Addressbook/Calendar/InfoLog):

Input	Meaning
invoice	substring "invoice" anywhere
invoice overdue	"invoice" OR "overdue" (default)
invoice and overdue	"invoice" AND "overdue"
invoice +overdue	"invoice" AND "overdue"
invoice -spam	"invoice" AND NOT "spam"
"invoice overdue"	literal phrase as a single token

The resulting IMAP query for invoice +overdue with TEXT search type is (BODY "invoice") (BODY "overdue") — two index lookups intersected by Dovecot (sub-millisecond with Flatcurve, two linear scans without).

A single-token input produces byte-identical output to the historical generator — no regression on existing user behaviour where they typed one word.

Files changed

• api/src/Mail.php — ~130 lines of effective delta

Test plan

• Manual UI testing on EGroupware 26.1 (Docker image), Dovecot with fts_flatcurve
• Multi-word search with words in arbitrary order — verified match
• Single-word search — verified identical output to before patch
• Negation - — verified AND NOT semantics
• Quoted phrase "foo bar" — verified historical contiguous match preserved
• Unit tests for buildTokenizedSearch() and parseSearchTokens() — happy to add as part of review

Backward compatibility

Fully preserved for single-word inputs. Multi-word inputs change semantics: previously they tried to match a literal contiguous substring (which almost never succeeded), now they apply the documented A B = A or B rule. Users who specifically relied on contiguous match (rare) can now wrap the value in double quotes to preserve the old semantics.

Related

• Forum discussion: https://help.egroupware.org/t/79137
• Companion patch for Sieve filter rules (separate PR): https://github.com/EGroupware/egroupware/pull/
• Code gist with the diff: https://gist.github.com/CActor/092c75d6394a0a37fd2b76fa3c2caf34