Sindbad~EG File Manager

# PHPMailer Installation Guide

## What is PHPMailer?
PHPMailer is a full-featured email creation and transfer library for PHP. It enables your application to send real emails via SMTP.

## Installation Steps

### 1. Install via Composer (Recommended)

Open your terminal/command prompt in the project root directory and run:

```bash
composer require phpmailer/phpmailer
```

Or if composer is not in your PATH:

```bash
php composer.phar require phpmailer/phpmailer
```

### 2. Verify Installation

After running the composer command, you should see:
- A new `vendor/` directory (if it didn't exist)
- PHPMailer files in `vendor/phpmailer/phpmailer/`
- Updated `composer.lock` file

### 3. Configure SMTP Settings

Go to **Dashboard → Email Management → SMTP Settings** and configure:

#### Gmail Example:
- **SMTP Host:** smtp.gmail.com
- **SMTP Port:** 587
- **SMTP Username:** your-email@gmail.com
- **SMTP Password:** your-app-password (not your regular password!)
- **Encryption:** TLS
- **From Email:** your-email@gmail.com
- **From Name:** Your Church Name

**Important for Gmail:** You need to:
1. Enable 2-Factor Authentication
2. Generate an "App Password" at https://myaccount.google.com/apppasswords
3. Use the App Password (not your regular password)

#### Office 365 / Outlook Example:
- **SMTP Host:** smtp.office365.com
- **SMTP Port:** 587
- **SMTP Username:** your-email@outlook.com
- **SMTP Password:** your-password
- **Encryption:** TLS

#### Generic SMTP Example:
- **SMTP Host:** mail.yourdomain.com
- **SMTP Port:** 587 (or 465 for SSL)
- **SMTP Username:** noreply@yourdomain.com
- **SMTP Password:** your-password
- **Encryption:** TLS (or SSL for port 465)

### 4. Enable Email System

1. Check "Enable Email System" in SMTP Settings
2. Click "Save Settings"
3. Click "Send Test Email" to verify configuration

### 5. Set Up Automatic Email Processing

**Option A: Cron Job (Linux/Mac)**
```bash
*/5 * * * * php /path/to/copmadinaarea/cron/process_emails.php
```

**Option B: Windows Task Scheduler**
1. Open Task Scheduler
2. Create Basic Task
3. Trigger: Run every 5 minutes
4. Action: Start a program
   - Program: `php.exe`
   - Arguments: `C:\xampp\htdocs\copmadinaarea\cron\process_emails.php`

**Option C: Manual Processing**
- Use the "Process Now" button on Email Management page
- Or visit: `your-domain.com/cron/process_emails.php?manual=1`

## Troubleshooting

### PHPMailer Not Loading
**Error:** "Class 'PHPMailer\PHPMailer\PHPMailer' not found"

**Solution:**
```bash
composer install
```

### Authentication Failed
**Error:** "SMTP Error: Could not authenticate"

**Solutions:**
- Check username and password are correct
- For Gmail: Use App Password, not regular password
- Verify SMTP host and port are correct
- Check if your hosting provider blocks outgoing SMTP

### Connection Timeout
**Error:** "SMTP connect() failed"

**Solutions:**
- Check firewall settings
- Verify port is not blocked
- Try alternative ports (587, 465, 25)
- Contact hosting provider about SMTP restrictions

### SSL Certificate Issues
**Error:** "SSL operation failed"

**Solution:** Add this before sending (NOT RECOMMENDED for production):
```php
$mail->SMTPOptions = array(
    'ssl' => array(
        'verify_peer' => false,
        'verify_peer_name' => false,
        'allow_self_signed' => true
    )
);
```

## Testing

1. Go to **Email Management → SMTP Settings**
2. Enter a test email address
3. Click "Send Test Email"
4. Check your inbox (and spam folder)

## Fallback Mode

If PHPMailer is not installed, the system will:
- Automatically fall back to simulation mode
- Log emails to error log instead of sending
- Continue working without errors
- Show a warning in Email Management

This allows development without SMTP configuration.

## Common SMTP Providers

### Gmail
- Host: smtp.gmail.com
- Port: 587 (TLS) or 465 (SSL)
- Requires: App Password

### Outlook/Office365
- Host: smtp.office365.com
- Port: 587
- Auth: Regular password

### Yahoo
- Host: smtp.mail.yahoo.com
- Port: 587 or 465
- Requires: App Password

### SendGrid
- Host: smtp.sendgrid.net
- Port: 587
- Username: apikey
- Password: Your SendGrid API Key

### Mailgun
- Host: smtp.mailgun.org
- Port: 587
- Auth: Your Mailgun credentials

## Support

If you continue having issues:
1. Check PHP error logs
2. Check email processor logs: `logs/email_processor.log`
3. Verify email settings in database: `email_settings` table
4. Test with a simple SMTP tester online

## Security Best Practices

1. ✅ Never commit SMTP passwords to version control
2. ✅ Use environment variables for sensitive data
3. ✅ Enable 2FA on email accounts
4. ✅ Use App Passwords instead of regular passwords
5. ✅ Limit SMTP access to specific IP addresses if possible
6. ✅ Monitor email queue for spam/abuse
7. ✅ Implement rate limiting for email sending

---

**Need Help?** Check the Email Management page for real-time system status and diagnostic information.