Skip to content

Releases: yaijs/php-ymap

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

19 Dec 02:59
@eypsilon eypsilon
v1.0.2
f5a5a73

Choose a tag to compare

View all tags
v1.0.2 - Production-Ready with PHP 8.4 Future-Proofing Latest
Latest

🏆 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.

Assets 2
Loading

v1.0.0 - Initial Release

09 Dec 08:21
@eypsilon eypsilon
v1.0.0
6a4fae0

Choose a tag to compare

View all tags
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', '[email protected]', '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',
    '[email protected]',
    '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' => '[email protected]',
        '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

🙏 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!

Loading