Added searching by UID

[szymekjanaczek]

Hi @Webklex,

I just added the possibility of searching for messages by their UID codes. Additionally, created some helper methods to simplify searching.

[szymekjanaczek]

@Webklex, should I improve anything?

[Webklex]

Hi @szymekjanaczek ,
could you provide a usage example? I'm not familiar with the UID search criteria.
Does it support to search for partial numbers? I would like to add it to the documentation.

Anyway many thanks for your pull request :)

Best regards,

[szymekjanaczek]

Hi, @Webklex

Sure, I can!

Theory and docs

[RFC 3501] - [2.3.1.1.] Unique Identifier (UID) Message Attribute

TLDR

Message UID is a unique code assigned to each message. It's persistent, which means that when we have for example this situation in our mailbox...

UID	Subject
1	Test-1
2	Test-2
3	Test-3

... and we remove the message with UID = 2, the message which has UID = 3 stays the number three:

UID	Subject
1	Test-1
3	Test-3

Disclaimer: UID is assigned separately per each folder. So when we move the message from one folder to another, it gets a new UID - the highest one free in a new folder.

Description

Let's suppose we want to get specific messages from the Inbox. Before my PR we only search them by various criteria like TEXT, SUBJECT, etc. But it's still searching. So what when we've to get some different entities?

Practical example:

Let's suppose we want to connect IMAP message entities with e.g. notes from the database.
So we have the database schema like this:

messages table:

path	uid	note
INBOX	1	foo
INBOX	5	bar
INBOX	7	lorem

And let's assume, we want to get from IMAP all messages with the assigned note.

// Let's mock an example database response from messages table.
$databaseMessages = [
    ['path' => 'INBOX', 'uid' => 1, 'note' => 'foo'],
    ['path' => 'INBOX', 'uid' => 5, 'note' => 'bar'],
    ['path' => 'INBOX', 'uid' => 7, 'note' => 'lorem'],
];

/** @var MessageCollection<Message> $messages */
$messages = $query->whereUidIn($uidList)->get();

/* 
 * Now we have a MessageCollection of Message entities.
 * we can iterate through them, to perform any action or just return this list as a response.
 */
foreach ($messages as $message) {
  $message->setFlag('Seen');
}

return $messages;

I'm not sure, what do you mean here:

Does it support to search for partial numbers?

Could you explain it, please? To let me answer.

[Webklex]

Thanks, that's perfect!

Never mind, by trying to answer it I answered my own question :D

I was thinking if it is possible to search for all uids which contain a certain number like 24 and find all existing uids (24, 124, 224, ..). I figured it is not likely and could be archived by simply building the uid query $uidList in a given sequence based on the last available uid.

Anyway thanks for taking your time and your contribution.

Best regards,

[szymekjanaczek]

That's great ;p

No, I don't know anything about this possibility in pure IMAP.
But... we can also use RAW UID queries (yes, I added this method too):

/** @var MessageCollection<Message> $messages */
$messages = $query->whereUid('1:3')->get();
$messages = $query->whereUid('1,3,5')->get();
$messages = $query->whereUid(1)->get();

[szymekjanaczek]

Can I do anything else to prepare this feature for release?
Could you, please, tell me @Webklex, when are you going to release it?

[Webklex]

Hi @szymekjanaczek ,
thanks for your patience. I just released a new version containing this pr: v2.7.1

Best regards,

[szymekjanaczek]

Great, thanks
Have a nice day!

[Webklex]

Thanks, you too :)