php-imap

PHP-IMAP is a PHP wrapper for IMAP communication that does not require the php-imap extension to be installed or enabled. It provides full protocol integration, supporting the IMAP IDLE operation and modern oAuth authentication processes.

While the extension is not required, enabling the php-imap module can improve message decoding quality and is necessary if you need to use legacy protocols like POP3.

The Header class can detect potential spoofing by comparing addresses found in from, reply_to, return_path, sender, and envelope_from headers.

If multiple distinct senders are detected, the header is marked as spoofed via $header->set('spoofed', true).

If the configuration key security.detect_spoofing_exception is set to true, the library will throw a Webklex\\PHPIMAP\\Exceptions\\SpoofingAttemptDetectedException instead of just marking the attribute.

The ClientManager implements the __call magic method, allowing you to call methods directly on the manager as if you were calling them on the default Client instance. This is a convenience feature to avoid calling ->account()->method() repeatedly.

// Instead of this:
$manager->account()->getFolder('INBOX');

// You can do this (proxies to the default account):
$manager->getFolder('INBOX');

When fetching large collections of messages, individual message retrieval might fail (e.g., due to corrupted content). The Query class handles this via a soft_fail mode:

• Soft Fail (Default/Enabled): If soft_fail is true, the query will continue even if some messages fail to fetch. You can check for errors using hasErrors() or hasError($uid) and retrieve them via errors() or error($uid).
• Hard Fail: If soft_fail is false, the first error encountered during get() or populate() will throw a GetMessagesFailedException.

To enable soft fail: $query->softFail(true);.

The Webklex\PHPIMAP\\Attribute class represents a single attribute within an IMAP response. It acts as a container for an attribute name and one or more associated values. It implements ArrayAccess, allowing you to interact with it like an array, and provides helper methods for common data transformations like converting to a date or a string.

use Webklex\PHPIMAP\Attribute;

// Create a new attribute with a name and a single value
$attribute = new Attribute('Subject', 'Hello World');

// Add more values
$attribute->add('Second Value');

// Access values like an array
$firstValue = $attribute[0];

// Convert to string (comma-separated values)
echo $attribute->toString(); // "Hello World, Second Value"

// Convert to array
$array = $attribute->toArray();

If you encounter the error Kerberos error: No credentials cache file found (try running kinit) (...), you can resolve it by:

1. Opening your configuration file.
2. Uncommenting the DISABLE_AUTHENTICATOR option.
3. Using the legacy-imap protocol.

You can modify the behavior of the Header instance by providing custom options via setOptions(array $config).

Key options include:

• boundary: A custom regex pattern used by getBoundary().
• rfc822: A boolean determining if the PHP imap_rfc822_parse_headers extension should be used if available.
• fallback_date: A string used as a fallback date if the message date fails to parse, preventing an InvalidMessageDateException.

$header->setOptions([
    'fallback_date' => 'now',
    'rfc822' => true
]);

Check the following compatibility table to ensure your PHP version is supported by the library version you are using:

To work with files attached to an email, use the following methods on a Message instance:

• hasAttachments(): Returns true if the message contains any attachments.
• attachments() or getAttachments(): Returns an AttachmentCollection containing all attachments.

if ($message->hasAttachments()) {
    foreach ($message->attachments() as $attachment) {
        // Process attachment
        echo $attachment->getName();
    }
}