ImapEngine

The ImapQueryBuilder allows for complex logical grouping:

• where(mixed $column, mixed $value = null): Adds an AND condition. If $column is a callable, it creates a nested condition group.
• orWhere(mixed $column, mixed $value = null): Adds an OR condition. If $column is a callable, it creates a nested condition group.
• whereNot(mixed $column, mixed $value = null): Adds an AND NOT condition.

Example of nested conditions:

$query = (new ImapQueryBuilder())
    ->where(function (ImapQueryBuilder $query) {
        $query->from('boss@company.com')
              ->subject('Urgent');
    })
    ->orWhere('flagged');

Greenmail can be run as a standalone service using Docker Compose. This service provides a mock IMAP/SMTP server for testing purposes.

By default, the service maps port 3143 to the host. You can configure the server behavior using the GREENMAIL_OPTS environment variable.

Common configuration flags for GREENMAIL_OPTS include:

• -Dgreenmail.setup.test.all: Sets up all test protocols.
• -Dgreenmail.hostname=0.0.0.0: Binds the server to all network interfaces.
• -Dgreenmail.auth.disabled: Disables authentication requirements.
• -Dgreenmail.verbose: Enables verbose logging.

services:
    greenmail:
        image: greenmail/standalone:latest
        environment:
            - GREENMAIL_OPTS=-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.auth.disabled -Dgreenmail.verbose
        ports:
            - "3143:3143"

You can use the following methods on a BodyStructurePart instance to determine how a part should be handled:

• isAttachment(): Returns true if the part is an attachment. It considers the ContentDisposition, but also treats non-text/html parts with a filename as attachments.
• isInline(): Returns true if the part is marked as inline via its disposition.
• isText(): Returns true if the type is text and subtype is plain.
• isHtml(): Returns true if the type is text and subtype is html.

You can add or remove flags from a message using the flag() method. This operation is performed on the server via the mailbox connection.

Parameters:

• $flag: A BackedEnum or string representing the flag.
• $operation: A string indicating the operation: '+' to add a flag or '-' to remove a flag.
• $expunge: (Optional) If true, calls expunge() on the folder after the operation.

Example:

// Add the 'Seen' flag and expunge the folder
$message->flag('Seen', '+', expunge: true);

// Remove the 'Deleted' flag
$message->flag('Deleted', '-');

The BodyStructurePart class provides methods to access metadata about a specific part of an email's body structure.

Available Metadata Methods

• partNumber(): Returns the part identifier (e.g., 1, 1.2).
• type(): Returns the MIME type (e.g., text, image, multipart).
• subtype(): Returns the MIME subtype (e.g., plain, html, jpeg).
• parameters(): Returns an associative array of all MIME parameters.
• parameter(string $name): Returns a specific parameter value by name (case-insensitive).
• id(): Returns the content ID.
• description(): Returns the decoded MIME description.
• encoding(): Returns the content transfer encoding.
• size(): Returns the size in bytes.
• lines(): Returns the number of lines (for text parts).
• disposition(): Returns a ContentDisposition object.
• charset(): Returns the character set from the parameters.

Use these methods for technical filtering:

• uid(int|string|array $from, int|float|null $to = null): Search within a range of UIDs. If $to is INF, it defaults to the maximum allowed IMAP UID (4294967295).
• larger(int $bytes): Messages larger than the specified number of bytes.
• smaller(int $bytes): Messages smaller than the specified number of bytes.

The ImapQueryBuilder provides a fluent interface for constructing complex IMAP search queries. It supports basic conditions (AND), OR conditions, and nested condition groups. You can chain various methods to filter emails by status, sender, recipient, date, subject, or specific headers.

To generate the final IMAP-compatible string, call the toImap() method. Use isEmpty() to check if any conditions have been added.

$query = (new ImapQueryBuilder())
    ->from('user@example.com')
    ->subject('Hello')
    ->since('2023-01-01')
    ->toImap();

You can generate URLs for navigating through pages using the following methods. These URLs will automatically include the path, the query parameters provided during construction, and the pageName parameter.

• url(int $page): Generates a URL for a specific page number.
• nextPageUrl(): Returns the URL for the next page, or null if no more pages exist.
• previousPageUrl(): Returns the URL for the previous page, or null if on the first page.

// Example of generating navigation links
$next = $paginator->nextPageUrl();
$prev = $paginator->previousPageUrl();
$pageThree = $paginator->url(3);