Download the PHP package yaijs/php-ymap without Composer

php-ymap

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.

Table of Contents

1. Features
2. Requirements
3. Installation
4. Usage
   • Low-Level Client
   • ImapService Fluent API
   • Array / Config-Driven Setup
   • Connection Options
5. Field & Filter Reference
6. Performance & Production Readiness
   • Real-World Benchmarks
   • Memory Optimization with FetchOptions
   • Shopware 6.7 Integration
7. Advanced Usage
8. Demo Application
9. Error Handling
10. Security
11. Development & Testing
12. Contributing
13. Troubleshooting
14. 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

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

Usage

Low-Level Client

ImapService Fluent API

Array / Config-Driven Setup

Connection Options

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

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

Field & Filter Reference

Available Fields

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

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

Flag Helpers

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):

Socket mode (default in v1.0.3):

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:

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:

Best Practices for Background Processing:

1. Use limit() to process emails in batches (recommend 20-50)
2. Always set includeAttachmentContent: false unless needed
3. Use saveAttachmentTo() for files larger than 5MB
4. Register ImapService in DI container, not static calls
5. 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:

Including Attachment Content in JSON APIs

Opt-in when you truly need the payload:

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:

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

Swap IMAP Transport at Service Level

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:

Current implementations:

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

Error Handling

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

Secure Connections

Always use SSL/TLS when connecting over untrusted networks:

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:

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

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

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.