v1.0.3 - Socket Mode Stabilized

php-ymap v1.0.3 - Socket Mode Stabilized

This release documents and hardens the connector path that works without ext-imap, aligned with PHP 8.4+ migration needs.

Highlights

• Default socket connector path is stable in production-like inboxes
• Fixed multipart body extraction regression (textBody / htmlBody empty cases)
• Fixed read/answered flag state persistence in fetch responses and demo workflows
• Improved IMAP search criteria handling for quoted tokens
• Composer metadata now treats ext-imap as optional (suggest) instead of required
• Verified on Vercel PHP 8.4 with ext-imap disabled.

Why this matters

You can now run php-ymap without php-imap enabled and still fetch/search/parse messages and update flags reliably across providers.

Installation

composer require yaijs/php-ymap:^1.0.3

Upgrade from v1.0.2

composer update yaijs/php-ymap

No API break is introduced in this patch release.

Notes for deployments

• ext-imap is optional in v1.0.3
• default runtime connector is SocketsImapConnection
• if needed, you can still force native extension mode using ExtImapConnection

Full changelog

See CHANGELOG.md.

v1.0.2 - Production-Ready with PHP 8.4 Future-Proofing

🏆 php-ymap v1.0.2 - The AI Council Approved Edition

ACHIEVEMENT UNLOCKED: First IMAP library with unanimous approval from 5+ AI models (Grok, Gemini, Codex, DeepSeek, Claude, ...).

This release adds a connection abstraction layer, memory-safe attachment streaming, and production benchmarks. Grok gave it 10/10 across all categories. We didn't just build a library — we made history. 🚀

🎯 Highlights

• ✅ PHP 8.4 Ready - Connection abstraction layer for when ext-imap moves to PECL
• ✅ Memory Safe - Stream large attachments without loading into memory
• ✅ Production Tested - Real-world benchmarks: 105-230ms per message across Gmail/ok.de/IONOS
• ✅ Fully Testable - Dependency injection support for mocking
• ✅ Zero Breaking Changes - Fully backward-compatible with v1.0.1

🔧 What's New

Connection Abstraction Layer

// Default: uses native ext-imap (no changes needed)
$client = new ImapClient($config);

// For testing: inject mock
$client = new ImapClient($config, connection: $mockConnection);

// Future (v2.0): pure PHP implementation
$client = new ImapClient($config, connection: new SocketImapConnection());

Memory-Safe Attachment Streaming

// Save 50MB+ files without memory exhaustion
$client->saveAttachmentTo($uid, $attachment, '/tmp/file.pdf');

// Control what gets loaded (60-80% memory reduction)
$options = new FetchOptions(
    includeAttachmentContent: false  // Critical for large files!
);

📊 Performance Benchmarks

Real-world testing across production IMAP servers:

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

🚀 Framework Ready

Designed for seamless integration with modern PHP frameworks and DI containers. See README for best practices.

📦 Installation

composer require yaijs/php-ymap:^1.0.2

🔄 Upgrading from v1.0.1

No breaking changes! Just run:

composer update yaijs/php-ymap

📝 Full Changelog

See CHANGELOG.md for complete details.

🙏 Credits

Development Team:

• Core architecture and connection abstraction
• Performance testing across production IMAP servers

The AI Council (Full Consensus Achieved):

• Grok - 10/10 full approval across all categories
• Gemini 3 Pro - Production readiness certification
• OpenAI Codex - Implementation validation
• DeepSeek - Additional validation
• Claude Sonnet 4.5 - Documentation & architecture

Grok's verdict: "This is the modern PHP IMAP client for 2025–2030. You orchestrated a full AI orchestra and made us all dance in perfect harmony. 🕺💃"

---

Ready for production deployment in plugins and enterprise applications.

v1.0.0 - Initial Release

🎉 php-ymap v1.0.0 - Initial Release

A lightweight, modern IMAP client library for PHP 8.1+ that makes reading and managing emails simple and enjoyable.

✨ Features

🔌 Simple Connection

• Fluent API - Chain methods for clean, readable code
• Array configuration - Pass config arrays for framework integration
• Connection testing - Verify credentials before use with ImapService::testConnection()

📬 Full Message Parsing

• Text & HTML bodies - Automatic charset conversion and multipart handling
• Attachments - Inline and regular attachments with metadata
• Decoded headers - MIME-encoded subjects and addresses handled automatically
• Address parsing - Structured email/name pairs for From, To, CC, BCC, Reply-To

🔍 Flexible Filtering

• IMAP-level search - Date ranges, read/unread, answered status, sender, recipient, subject, body
• Post-fetch exclusion - Filter by sender patterns and subject keywords after retrieval
• Field selection - Fetch only the data you need (UIDs, subjects, bodies, attachments, etc.)

✉️ Flag Management

• Mark messages as read/unread
• Mark messages as answered/unanswered
• Bulk operations with arrays of UIDs

🧱 Robust Implementation

• Charset handling - UTF-8 conversion with iconv
• FT_PEEK support - Read messages without marking them as seen
• Error handling - Specific exceptions for connection and fetch failures
• PHPStan Level 8 - Strict type safety and code quality

🖥️ Demo Application

• Modern, responsive HTML interface
• Real-time message filtering and flag management
• Powered by YEH (Yai Event Hub) for clean event delegation
• Perfect reference implementation

---

📦 Installation

composer require yaijs/php-ymap

Requirements:

• PHP 8.1+
• Extensions: IMAP, mbstring, iconv, JSON

Enable IMAP on Ubuntu/Debian:

sudo apt install php8.2-imap && sudo phpenmod imap

---

🚀 Quick Start

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'])
    ->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";
}

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);
}

Array Configuration

use Yai\Ymap\ImapService;

$imap = new ImapService([
    'connection' => [
        'mailbox' => '{imap.gmail.com:993/imap/ssl}INBOX',
        'username' => 'user@example.com',
        'password' => 'app-password',
    ],
    '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();

---

📚 Documentation

Full documentation available in the README:

• Connection options and parameters
• Available fields reference
• Filter methods (IMAP and post-fetch)
• Flag management helpers
• Error handling guide
• Troubleshooting tips

---

🎯 Demo Application

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

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

The demo showcases:

• Interactive message browsing
• Real-time filtering
• Flag management
• Modern UI powered by YEH

---

🛡️ Code Quality

• ✅ PHPStan Level 8 - Maximum static analysis strictness
• ✅ Strict types - declare(strict_types=1) throughout
• ✅ Full type hints - Properties, parameters, return types
• ✅ Clean architecture - Separation between low-level and high-level APIs
• ✅ Immutable objects - Thread-safe message representation

---

🌟 Why php-ymap?

Clean & Modern

• PHP 8.1+ features (constructor property promotion, match expressions, union types)
• Fluent, chainable API for readable code
• No global functions or side effects

Developer-Friendly

• Comprehensive examples in README
• Working demo application
• Clear error messages with context

Production-Ready

• Battle-tested IMAP operations
• Proper character encoding handling
• Graceful error handling

Lightweight

• Zero dependencies (only PHP extensions)
• Minimal abstraction overhead
• PSR-4 autoloading

---

📝 Example Use Cases

• Email notifications - Monitor inbox for specific messages
• Support ticket systems - Parse incoming support emails
• Email automation - Process and flag messages programmatically
• Inbox cleanup - Bulk operations on filtered messages
• Email analytics - Extract and analyze message data
• Integration testing - Verify email delivery in tests

---

🤝 Contributing

Contributions welcome! Please:

• Follow existing code style
• Maintain PHPStan level 8 compliance
• Add tests for new features
• Update documentation

---

📄 License

MIT License - see LICENSE for details.

Copyright © 2025 Engin Ypsilon

---

🔗 Links

• GitHub: https://github.com/yaijs/php-ymap
• Packagist: https://packagist.org/packages/yaijs/php-ymap
• YAI Toolkit: https://yaijs.github.io/yai
• YEH Documentation: https://yaijs.github.io/yai/docs/yeh/

---

🙏 Acknowledgments

Built with modern PHP practices and showcasing the power of YEH for event-driven interfaces.

---

Enjoy using php-ymap! 🚀

If you find this library helpful, please ⭐ star the repository on GitHub!