Skip to content

v1.0.0 - Initial Release

Choose a tag to compare

View all tags
@eypsilon eypsilon released this 09 Dec 08:21
· 21 commits to main since this release
v1.0.0
6a4fae0

🎉 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

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

Assets 2
Loading