# IMAP Alternatives for PHP 8.4
**Date**: 2025-12-04  
**Issue**: PECL IMAP extension incompatible with PHP 8.4

---

## 🚨 **THE PROBLEM**

The PECL IMAP extension (v1.0.3) fails to compile with PHP 8.4 due to:
- Incompatibility with imap-uw library
- Missing U8T_CANONICAL constant
- utf8_mime2text() signature changes

---

## ✅ **SOLUTION OPTIONS**

### **Option 1: Downgrade to PHP 8.3 (EASIEST)**

PHP 8.3 has better PECL extension support.

```bash
# Unlink current PHP
brew unlink php

# Install PHP 8.3
brew install php@8.3

# Link PHP 8.3
brew link php@8.3 --force --overwrite

# Verify version
php -v

# Install IMAP extension
pecl install imap

# Enable extension
echo 'extension="imap.so"' >> $(php --ini | grep "Configuration File (php.ini) Path" | cut -d: -f2 | xargs)/php.ini

# Verify
php -m | grep imap
```

**Pros**:
- ✅ IMAP extension works perfectly
- ✅ All existing code works
- ✅ Easy to install

**Cons**:
- ⚠️ Not using latest PHP version

---

### **Option 2: Use PHP IMAP Library (Composer Package)**

Use a pure PHP IMAP library that doesn't require the C extension.

**Install via Composer**:
```bash
composer require php-imap/php-imap
```

**Pros**:
- ✅ Works with PHP 8.4
- ✅ No C extension needed
- ✅ Well-maintained library

**Cons**:
- ⚠️ Requires code changes
- ⚠️ May be slower than C extension

---

### **Option 3: Use Webklex IMAP Library**

Another popular pure PHP IMAP library.

**Install via Composer**:
```bash
composer require webklex/php-imap
```

**Pros**:
- ✅ Works with PHP 8.4
- ✅ Modern, well-documented
- ✅ Active development

**Cons**:
- ⚠️ Requires code changes

---

### **Option 4: Wait for PECL IMAP Update**

Wait for PECL to release a PHP 8.4 compatible version.

**Pros**:
- ✅ No code changes needed
- ✅ Native C performance

**Cons**:
- ❌ Unknown timeline
- ❌ Can't use IMAP sync now

---

## 🎯 **RECOMMENDED SOLUTION**

**For immediate use**: **Downgrade to PHP 8.3**

This is the fastest way to get IMAP working with minimal changes.

---

## 📋 **QUICK INSTALL: PHP 8.3 + IMAP**

Run these commands:

```bash
# Unlink PHP 8.4
brew unlink php

# Install PHP 8.3
brew install php@8.3

# Link PHP 8.3
brew link php@8.3 --force --overwrite

# Verify version
php -v

# Install IMAP extension
printf "/opt/homebrew/opt/imap-uw\n" | pecl install imap

# Enable extension
echo 'extension="imap.so"' >> /opt/homebrew/etc/php/8.3/php.ini

# Restart PHP-FPM
brew services restart php@8.3

# Verify IMAP is loaded
php -m | grep imap
```

---

## 🔄 **SWITCHING BACK TO PHP 8.4 LATER**

If you want to switch back to PHP 8.4 later:

```bash
brew unlink php@8.3
brew link php --force --overwrite
```

---

## 📊 **COMPARISON TABLE**

| Solution | Difficulty | Time | PHP 8.4 | Performance | Code Changes |
|----------|-----------|------|---------|-------------|--------------|
| PHP 8.3 | ⭐ Easy | 5 min | ❌ No | ⚡ Fast | ✅ None |
| php-imap/php-imap | ⭐⭐ Medium | 30 min | ✅ Yes | 🐢 Slower | ⚠️ Major |
| webklex/php-imap | ⭐⭐ Medium | 30 min | ✅ Yes | 🐢 Slower | ⚠️ Major |
| Wait for update | ⭐ Easy | ❓ Unknown | ✅ Yes | ⚡ Fast | ✅ None |

---

## 🚀 **NEXT STEPS**

**Choose your solution**:

**A.** Downgrade to PHP 8.3 (recommended for now)  
**B.** Use Composer IMAP library (requires code rewrite)  
**C.** Wait for PECL update (no timeline)

Let me know which option you prefer, and I'll help you implement it!