ddeboer/imap

Object-oriented IMAP for PHP

Friday, July 20, 2018
by ddeboer
Repository
28 Watchers
406 Stars
200,273 Installations

PHP
8 Dependents
0 Suggesters
187 Forks
24 Open issues
36 Versions
15 % Grown

The README.md

PHP IMAP library

, _(*1)

A PHP IMAP library to read and process e-mails over IMAP protocol, built with robust Object-Oriented architecture., _(*2)

This library requires PHP >= 8.3 with IMAP, iconv and Multibyte String extensions installed., _(*3)

Installation

The recommended way to install the IMAP library is through Composer:, _(*4)

$ composer require ddeboer/imap

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation., _(*5)

Usage

Connect and Authenticate

use Ddeboer\Imap\Server;

$server = new Server('imap.gmail.com');

// $connection is instance of \Ddeboer\Imap\Connection
$connection = $server->authenticate('my_username', 'my_password');

You can specify port, flags and parameters to the server:, _(*6)

$server = new Server(
    $hostname, // required
    $port,     // defaults to '993'
    $flags,    // defaults to '/imap/ssl/validate-cert'
    $parameters
);

Mailboxes

Retrieve mailboxes (also known as mail folders) from the mail server and iterate over them:, _(*7)

$mailboxes = $connection->getMailboxes();

foreach ($mailboxes as $mailbox) {
    // Skip container-only mailboxes
    // @see https://secure.php.net/manual/en/function.imap-getmailboxes.php
    if ($mailbox->getAttributes() & \LATT_NOSELECT) {
        continue;
    }

    // $mailbox is instance of \Ddeboer\Imap\Mailbox
    printf('Mailbox "%s" has %s messages', $mailbox->getName(), $mailbox->count());
}

Or retrieve a specific mailbox:, _(*8)

$mailbox = $connection->getMailbox('INBOX');

Delete a mailbox:, _(*9)

$connection->deleteMailbox($mailbox);

You can bulk set, or clear, any flag of mailbox messages (by UIDs):, _(*10)

$mailbox->setFlag('\\Seen \\Flagged', ['1:5', '7', '9']);
$mailbox->setFlag('\\Seen', '1,3,5,6:8');

$mailbox->clearFlag('\\Flagged', '1,3');

WARNING You must retrieve new Message instances in case of bulk modify flags to refresh the single Messages flags., _(*11)

Messages

Retrieve messages (e-mails) from a mailbox and iterate over them:, _(*12)

$messages = $mailbox->getMessages();

foreach ($messages as $message) {
    // $message is instance of \Ddeboer\Imap\Message
}

To insert a new message (that just has been sent) into the Sent mailbox and flag it as seen:, _(*13)

$mailbox = $connection->getMailbox('Sent');
$mailbox->addMessage($messageMIME, '\\Seen');

Note that the message should be a string at MIME format (as described in the RFC2045)., _(*14)

Searching for Messages

use Ddeboer\Imap\SearchExpression;
use Ddeboer\Imap\Search\Email\To;
use Ddeboer\Imap\Search\Text\Body;

$search = new SearchExpression();
$search->addCondition(new To('me@here.com'));
$search->addCondition(new Body('contents'));

$messages = $mailbox->getMessages($search);

WARNING We are currently unable to have both spaces and double-quotes escaped together. Only spaces are currently escaped correctly. You can use Ddeboer\Imap\Search\RawExpression to write the complete search condition by yourself., _(*15)

Messages can also be retrieved sorted as per imap_sort function:, _(*16)

$today = new DateTimeImmutable();
$thirtyDaysAgo = $today->sub(new DateInterval('P30D'));

$messages = $mailbox->getMessages(
    new Ddeboer\Imap\Search\Date\Since($thirtyDaysAgo),
    \SORTDATE, // Sort criteria
    true // Descending order
);

Unknown search criterion: OR

Note that PHP imap library relies on the c-client library available at https://www.washington.edu/imap/ which doesn't fully support some IMAP4 search criteria like OR. If you want those unsupported criteria, you need to manually patch the latest version (imap-2007f of 23-Jul-2011 at the time of this commit) and recompile PHP onto your patched c-client library., _(*17)

By the way most of the common search criteria are available and functioning, browse them in ./src/Search., _(*18)

References:, _(*19)

https://stackoverflow.com/questions/36356715/imap-search-unknown-search-criterion-or
imap-2007f.tar.gz: ./src/c-client/mail.c and ./docs/internal.txt

Message Properties and Operations

Get message number and unique message id in the form ...:, _(*20)

$message->getNumber();
$message->getId();

Get other message properties:, _(*21)

$message->getSubject();
$message->getFrom();    // Message\EmailAddress
$message->getTo();      // array of Message\EmailAddress
$message->getDate();    // DateTimeImmutable
$message->isAnswered();
$message->isDeleted();
$message->isDraft();
$message->isSeen();

Get message headers as a \Ddeboer\Imap\Message\Headers object:, _(*22)

$message->getHeaders();

Get message body as HTML or plain text (only first part):, _(*23)

$message->getBodyHtml();    // Content of text/html part, if present
$message->getBodyText();    // Content of text/plain part, if present

Get complete body (all parts):, _(*24)

$body = $message->getCompleteBodyHtml();    // Content of text/html part, if present
if ($body === null) { // If body is null, there are no HTML parts, so let's try getting the text body
    $body = $message->getCompleteBodyText();    // Content of text/plain part, if present
}

Reading the message body keeps the message as unseen. If you want to mark the message as seen:, _(*25)

$message->markAsSeen();

Or you can set, or clear, any flag:, _(*26)

$message->setFlag('\\Seen \\Flagged');
$message->clearFlag('\\Flagged');

Move a message to another mailbox:, _(*27)

$mailbox = $connection->getMailbox('another-mailbox');
$message->move($mailbox);

Deleting messages:, _(*28)

$mailbox->getMessage(1)->delete();
$mailbox->getMessage(2)->delete();
$connection->expunge();

Get message attachments (both inline and attached) and iterate over them:, _(*29)

$attachments = $message->getAttachments();

foreach ($attachments as $attachment) {
    // $attachment is instance of \Ddeboer\Imap\Message\Attachment
}

Download a message attachment to a local file:, _(*30)

// getDecodedContent() decodes the attachment’s contents automatically:
file_put_contents(
    '/my/local/dir/' . $attachment->getFilename(),
    $attachment->getDecodedContent()
);

Embedded Messages

Check if attachment is embedded message and get it:, _(*31)

$attachments = $message->getAttachments();

foreach ($attachments as $attachment) {
    if ($attachment->isEmbeddedMessage()) {
        $embeddedMessage = $attachment->getEmbeddedMessage();
        // $embeddedMessage is instance of \Ddeboer\Imap\Message\EmbeddedMessage
    }
}

An EmbeddedMessage has the same API as a normal Message, apart from flags and operations like copy, move or delete., _(*32)

Timeouts

The IMAP extension provides the imap_timeout function to adjust the timeout seconds for various operations., _(*33)

However the extension's implementation doesn't link the functionality to a specific context or connection, instead they are global. So in order to not affect functionalities outside this library, we had to choose whether wrap every imap_* call around an optional user-provided timeout or leave this task to the user., _(*34)

Because of the heterogeneous world of IMAP servers and the high complexity burden cost for such a little gain of the former, we chose the latter., _(*35)

Mock the library

Mockability is granted by interfaces present for each API. Dig into MockabilityTest for an example of a mocked workflow., _(*36)

Contributing: run the build locally

Docker is needed to run the build on your computer., _(*37)

First command you need to run is make start-imap-server, which starts an IMAP server locally., _(*38)

Then the local build can be triggered with a bare make., _(*39)

When you finish the development, stop the local IMAP server with make stop-imap-server., _(*40)

The Versions

20/07 2018

dev-master

9999999-dev

Object-oriented IMAP for PHP

library imap

Object-oriented IMAP for PHP

ddeboer/imap

The README.md

PHP IMAP library

Installation

Usage

Connect and Authenticate

Mailboxes

Messages

Searching for Messages

Unknown search criterion: OR

Message Properties and Operations

Message Attachments

Embedded Messages

Timeouts

Mock the library

Contributing: run the build locally

The Versions

dev-master

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.5.3

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.5.2

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.5.1

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.5.0

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.4.1

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.4.0

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.3.1

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.3.0

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.2.3

The Requires

The Development Requires

by David de Boer

by Community contributors

by Filippo Tessarotto

1.2.2