README

A lightweight fluent IMAP client for PHP 8.1+. Decode bodies, attachments, and headers, filter in one call, toggle flags, and preview everything via the included UI demo.

Features
Requirements
Installation
Usage
Field & Filter Reference
Performance & Production Readiness
Advanced Usage
Demo Application
Error Handling
Security
Development & Testing
Contributing
Troubleshooting
License

🏆 v1.0.3 - Socket Mode Stabilized! php-ymap now runs reliably without ext-imap, including restored multipart body parsing and persisted read/answered flags in real inbox workflows. See what's new →

Features

🔌 Simple connection – configure once with an array or chain fluent setters
📬 Full message parsing – text/HTML bodies, decoded attachments, cleaned headers
🔍 Flexible filtering – IMAP-level search plus post-fetch "exclude" filters
🎯 Field selection – fetch only what you need (UIDs, bodies, addresses, attachments…)
✉️ Flag helpers – mark messages read/unread/answered in a single call
🧱 Encodings handled – charset conversion and proper multipart parsing baked in
🖥️ Demo UI – modern HTML frontend for manual testing and QA
🚀 Production-ready – Memory-safe attachment streaming, tested on Gmail/ok.de/IONOS
🧪 Testable – Dependency injection support for mocking in unit tests

Requirements

PHP 8.1+
Required extensions: mbstring, iconv, JSON
Optional extension: ext-imap (for explicit ExtImapConnection usage)
Default runtime connector: pure PHP sockets (SocketsImapConnection)

Installation

composer require yaijs/php-ymap

The package ships with PSR‑4 autoloading (Yai\Ymap\*) and no global functions.

Usage

Low-Level Client

use Yai\Ymap\ConnectionConfig;
use Yai\Ymap\ImapClient;

$config = new ConnectionConfig(
    '{imap.gmail.com:993/imap/ssl}INBOX',
    'user@example.com',
    'app-password'
);

$client = new ImapClient($config);
$client->connect();

foreach ($client->getUnreadUids() as $uid) {
    $message = $client->fetchMessage($uid);
    echo $message->getSubject();
    $client->markAsRead($uid);
}

ImapService Fluent API

use Yai\Ymap\ImapService;

$messages = ImapService::create()
    ->connect('{imap.gmail.com:993/imap/ssl}INBOX', 'user@example.com', 'app-password')
    ->fields(['uid', 'subject', 'from', 'date', 'textBody'])
    ->includeAttachmentContent(false) // enable later if you need binary payloads
    ->since('2024-01-01')
    ->unreadOnly()
    ->excludeFrom(['noreply@', 'newsletter@'])
    ->limit(20)
    ->orderBy('desc')
    ->getMessages();

foreach ($messages as $msg) {
    echo "{$msg['subject']} from {$msg['from'][0]['email']}\n";
}

Array / Config-Driven Setup

use Yai\Ymap\ImapService;

$imap = new ImapService([
    'connection' => [
        'mailbox' => '{imap.gmail.com:993/imap/ssl}INBOX',
        'username' => 'user@example.com',
        'password' => 'app-password',
        'options' => 0,
        'retries' => 3,
        'parameters' => [
            'DISABLE_AUTHENTICATOR' => 'GSSAPI',
        ],
    ],
    'fields' => ['uid', 'subject', 'from', 'date', 'textBody'],
    'filters' => [
        'limit' => 10,
        'since' => '2024-01-01',
        'unread' => true,
    ],
    'exclude' => [
        'from' => ['noreply@', 'newsletter@'],
        'subject_contains' => ['Unsubscribe', 'Digest'],
    ],
]);

$messages = $imap->getMessages();

Connection Options

ImapService::connect() (and the connection config section) keep imap_open()-compatible parameters so existing configs continue to work in both connector modes:

Option	Description
`mailbox`	IMAP path, e.g. `{imap.gmail.com:993/imap/ssl}INBOX`
`username`, `password`	Credentials or app password
`options`	`imap_open()` bitmask compatibility field
`retries`	Retry count compatibility field
`parameters`	Optional connector parameters (TLS/auth behavior where supported)
`encoding`	Target encoding for decoded bodies (default `UTF-8`)

Need a lightweight “Test Credentials” button? Call the static helper:

use Yai\Ymap\ImapService;
use Yai\Ymap\Exceptions\ConnectionException;

try {
    ImapService::testConnection(
        '{imap.gmail.com:993/imap/ssl}INBOX',
        'user@example.com',
        'app-password'
    );
    echo 'Connection OK!';
} catch (ConnectionException $e) {
    echo 'Failed: ' . $e->getMessage();
}

Field & Filter Reference

Available Fields

Field	Description
`uid`	Message UID (always included)
`subject`	Decoded subject
`date`, `dateRaw`	Formatted string (`Y-m-d H:i:s`) or original `DateTimeImmutable\|null`
`from`, `to`, `cc`, `bcc`, `replyTo`	Address arrays (`email` + optional `name`)
`textBody`, `htmlBody`	Plain text and HTML bodies (decoded, concatenated per part)
`preview`	Plain text summary (auto-generated from text or stripped HTML)
`attachments`	Filename, MIME type, size (inline + regular attachments)
`headers`	Normalized header map
`seen`, `answered`	Boolean flags mirrored from IMAP
`size`	Total message size (bytes)

Use fields([...]) and/or excludeFields([...]) to tailor responses. uid is injected automatically.

Note on Attachments: The attachments field returns metadata by default. Payloads are decoded lazily to keep memory usage small, and you can opt into array payloads with includeAttachmentContent() or stream the bytes straight to disk with ImapClient::saveAttachmentTo().

Filter Methods

Method	IMAP Criteria
`since($date)`	`SINCE`
`before($date)`	`BEFORE` (inclusive)
`unreadOnly()` / `readOnly()`	`UNSEEN` / `SEEN`
`from($email)` / `to($email)`	`FROM` / `TO`
`subjectContains($text)`	`SUBJECT`
`bodyContains($text)`	`BODY`
`limit($n)`, `orderBy('asc'	'desc')`
`answeredOnly()`, `unansweredOnly()`	`ANSWERED` / `UNANSWERED`

Post-fetch exclusions (evaluated after message parsing) help drop noisy senders or subjects:

$imap->excludeFrom(['noreply@', 'quora.com'])
     ->excludeSubjectContains(['Unsubscribe', 'Digest']);

Flag Helpers

$imap->markAsRead([1234, 1235]);
$imap->markAsUnread(1236);
$imap->markAsAnswered(1237);
$imap->markAsUnanswered(1238);

Under the hood this proxies to imap_setflag_full() / imap_clearflag_full() using UIDs.

Performance & Production Readiness

php-ymap has been tested in production environments and optimized for enterprise use, including message queue workers and scheduled tasks.

Real-World Benchmarks

Performance tested across three production IMAP servers in both connector modes.

ext-imap mode (reference):

Provider	10 msgs	25 msgs	50 msgs	100 msgs	Avg/msg
ok.de	1.05s	2.25s	4.65s	7.79s	~105ms
IONOS	2.30s	5.83s	12.57s	-	~230ms
Gmail	3.43s	6.12s	11.86s	22.62s	~226ms

Socket mode (default in v1.0.3):

Provider	10 msgs	25 msgs	50 msgs	100 msgs	Avg/msg
ok.de	1.4282s	3.0770s	5.8331s	11.3149s	~113ms
IONOS	3.5413s	5.8178s	16.9986s	-	~340ms
Gmail	5.7557s	13.0100s	22.1389s	37.4546s	~375ms

Note: IONOS mailbox had 61 messages, so no 100-message run in either mode.

Key Takeaways:

Socket mode remains stable without ext-imap across tested providers
Throughput is lower in socket mode (expected in pure PHP transport)
Linear scaling up to 100 messages where mailbox size allows it
Handles 18MB+ datasets efficiently
Suitable for scheduled tasks and background processing
Memory-safe with proper FetchOptions configuration

Memory Optimization with FetchOptions

Control exactly what gets loaded into memory to prevent exhaustion in long-running processes:

use Yai\Ymap\FetchOptions;

// Lightweight: Only metadata for inbox listings
$options = new FetchOptions(
    includeTextBody: false,
    includeHtmlBody: false,
    includeAttachmentMetadata: true,
    includeAttachmentContent: false  // ← Critical for large attachments!
);

$messages = $service->getMessages($options);

Performance Impact:

60-80% reduction in memory usage for list views
Prevents memory exhaustion with 50MB+ attachments
Ideal for scheduled tasks processing hundreds of emails

Plugin Integration Example

php-ymap is designed for seamless integration with modern PHP frameworks and DI containers:

// In your service configuration (e.g., services.xml, services.yaml)
<service id="YourApp\Service\EmailProcessorService">
    <argument type="service" id="Yai\Ymap\ImapService"/>
</service>

// In your scheduled task or background job
class EmailProcessorTask
{
    public function run(): void
    {
        $messages = $this->imapService
            ->fields(['uid', 'subject', 'from', 'preview'])
            ->limit(20)  // Process in batches
            ->unreadOnly()
            ->getMessages();

        foreach ($messages as $msg) {
            // Process message...
            $this->imapService->markAsRead($msg['uid']);
        }
    }
}

Best Practices for Background Processing:

Use limit() to process emails in batches (recommend 20-50)
Always set includeAttachmentContent: false unless needed
Use saveAttachmentTo() for files larger than 5MB
Register ImapService in DI container, not static calls
Handle ConnectionException gracefully to avoid task crashes

Advanced Usage

Working with Attachment Content

Attachments are decoded lazily so you only pay for what you touch. You can still grab bytes directly or stream them to disk without ever holding them in memory:

use Yai\Ymap\ImapClient;
use Yai\Ymap\ConnectionConfig;

$config = new ConnectionConfig(
    '{imap.gmail.com:993/imap/ssl}INBOX',
    'user@example.com',
    'app-password'
);

$client = new ImapClient($config);
$client->connect();

$message = $client->fetchMessage(12345);

foreach ($message->getAttachments() as $attachment) {
    // Stream directly to the filesystem (no giant strings in memory)
    $client->saveAttachmentTo(
        $message->getUid(),
        $attachment,
        '/tmp/' . $attachment->getFilename()
    );

    // Or access the content lazily
    if ($attachment->getMimeType() === 'application/pdf') {
        processPdf($attachment->getContent());
    }

    if ($attachment->isInline()) {
        $contentId = $attachment->getContentId(); // For referencing in HTML
    }
}

Including Attachment Content in JSON APIs

Opt-in when you truly need the payload:

$messages = ImapService::create()
    ->connect('{imap.gmail.com:993/imap/ssl}INBOX', 'user@example.com', 'app-password')
    ->fields(['uid', 'subject', 'attachments'])
    ->includeAttachmentContent(true) // base64 by default
    ->getMessages();

foreach ($messages as $msg) {
    foreach ($msg['attachments'] as $attachment) {
        $binary = base64_decode($attachment['content']);
        // …
    }
}

Note: Including attachment content in JSON responses can significantly increase response size. Enable it only when necessary or stream to disk with saveAttachmentTo() for very large files.

Demo Application

Run the bundled dashboard to experiment with filters and see real responses:

cd php-ymap/example
php -S localhost:8000
# open http://localhost:8000

The frontend (built with YEH) posts to get.php, which uses ImapService exclusively. The JSON API is a good reference if you want to plug php-ymap into another UI.

Dependency Injection & Testing

php-ymap is built with testability in mind. The connection layer is fully abstracted via ImapConnectionInterface, making it easy to mock for tests.

Mock Connection for Unit Tests

use Yai\Ymap\ImapClient;
use Yai\Ymap\Connection\ImapConnectionInterface;

// Create a mock connection (PHPUnit example)
$mockConnection = $this->createMock(ImapConnectionInterface::class);
$mockConnection->method('search')
    ->willReturn([1, 2, 3]);

// Inject into ImapClient
$client = new ImapClient($config, connection: $mockConnection);

// Now $client->searchUIDs() returns mocked data

Swap IMAP Transport at Service Level

use Yai\Ymap\ImapService;
use Yai\Ymap\ImapClientInterface;

$service = ImapService::create()
    ->connect('{imap.host:993/imap/ssl}INBOX', 'user@example.com', 'secret')
    ->useClient($container->get(ImapClientInterface::class));

You can also call withClientFactory() to inject a factory that builds clients per connection config.

Connector Selection (PHP 8.4+ Ready)

The ImapConnectionInterface abstraction keeps php-ymap portable across environments with and without ext-imap:

use Yai\Ymap\Connection\ExtImapConnection;      // Optional: wraps ext-imap
use Yai\Ymap\Connection\SocketsImapConnection;  // Default: pure PHP socket connector

// Default in v1.0.3+: socket connector
$client = new ImapClient($config); // Uses SocketsImapConnection

// Optional override to native extension connector
$client = new ImapClient($config, connection: new ExtImapConnection());

Current implementations:

SocketsImapConnection - Pure PHP socket implementation (default)
ExtImapConnection - Wraps native PHP imap_* functions (optional)
Custom implementations welcome via ImapConnectionInterface

Error Handling

use Yai\Ymap\Exceptions\ConnectionException;
use Yai\Ymap\Exceptions\MessageFetchException;

try {
    $messages = $imap->getMessages();
} catch (ConnectionException $e) {
    // Invalid credentials, TLS failure, server unreachable, etc.
} catch (MessageFetchException $e) {
    // Individual message could not be parsed/fetched
}

// Optional: capture per-message failures instead of silently skipping
$imap->onError(static function (int $uid, \Throwable $e): void {
    error_log(sprintf('Failed to fetch UID %d: %s', $uid, $e->getMessage()));
});

ImapService::disconnect() lets you explicitly close the IMAP stream ($imap->disconnect(true) to expunge).

Security

Important: Never hardcode IMAP credentials in your source code.

Secure Credential Management

use Yai\Ymap\ImapService;

// ✓ Good: Use environment variables
$messages = ImapService::create()
    ->connect(
        getenv('IMAP_MAILBOX'),
        getenv('IMAP_USER'),
        getenv('IMAP_PASS')
    )
    ->getMessages();

// ✗ Bad: Hardcoded credentials
$messages = ImapService::create()
    ->connect('{imap.gmail.com:993/imap/ssl}INBOX', 'user@example.com', 'password')
    ->getMessages();

Secure Connections

Always use SSL/TLS when connecting over untrusted networks:

// ✓ Good: SSL enabled
'{imap.gmail.com:993/imap/ssl}INBOX'

// ⚠️ Warning: Disables certificate validation (development only)
'{imap.example.com:993/imap/ssl/novalidate-cert}INBOX'

Additional Security Practices

Limit result sets to prevent resource exhaustion (->limit(100))
Sanitize filenames before saving attachments to disk (see example below)
Validate MIME types when processing attachments
Implement rate limiting for web-facing IMAP operations
Use field selection to minimize data exposure (->fields(['uid', 'subject']))
Stream large attachments to prevent memory exhaustion attacks

Secure Attachment Handling

Always sanitize attachment filenames to prevent path traversal attacks:

function sanitizeFilename(string $filename): string {
    // Remove path traversal attempts
    $filename = basename($filename);

    // Remove dangerous characters
    $filename = preg_replace('/[^a-zA-Z0-9._-]/', '_', $filename);

    // Prevent hidden files
    $filename = ltrim($filename, '.');

    return $filename ?: 'attachment.bin';
}

// Use it when saving attachments
foreach ($message->getAttachments() as $attachment) {
    $safeName = sanitizeFilename($attachment->getFilename());
    $client->saveAttachmentTo($message->getUid(), $attachment, "/secure/path/{$safeName}");
}

Memory Safety: For attachments larger than your memory_limit, always use saveAttachmentTo() which streams directly to disk without loading into memory.

For detailed security guidelines, vulnerability reporting, and best practices, see SECURITY.md.

Development & Testing

composer install
./vendor/bin/phpstan analyse src/
# (optional) ./vendor/bin/phpunit

No additional tooling is required. PHPStan level is configured in phpstan.neon.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on:

Code standards and style (PHP 8.1+, strict typing, PHPStan level 8)
Pull request process
What to contribute (bug fixes, docs, tests, performance improvements)
How to report issues

For security vulnerabilities, please see our Security Policy instead of opening a public issue.

Troubleshooting

Issue	Hint
“Can't connect to mailbox”	Double-check mailbox path, host firewall, TLS flags, and credentials
Gmail authentication fails	Use an App Password; basic auth is blocked
Empty `textBody`	Some emails are HTML-only – read `htmlBody` or strip tags yourself (see example app)
Self-signed certs	Provide stream context via `parameters` (e.g. `['DISABLE_AUTHENTICATOR' => 'PLAIN']`, or TLS context)
Need ext-imap anyway	`sudo apt install php8.2-imap && sudo phpenmod imap` (optional, not required for default socket mode)

License

MIT. Portions of the IMAP protocol implementation and message helpers are derived from the MIT-licensed Webklex/php-imap and ddeboer/imap projects; see THIRD_PARTY_LICENSES.md for the preserved upstream notices you must include when redistributing this library or products that bundle it.

yaijs / php-ymap

Maintainers

Details