feat: Complete email debugging toolkit and comprehensive guide
�� New Diagnostic Tools: 1. check-settings.php - Notification system mode - Email channel status - Event configuration - Template configuration - Hook registration - Action Scheduler stats - Queued emails - Recommendations 2. test-email-direct.php - Queue test email - Manually trigger sendNow() - Test wp_mail() directly - Check wp_options - Check Action Scheduler - Verify email sent 3. EMAIL_DEBUGGING_GUIDE.md - Complete troubleshooting guide - Common issues & solutions - Expected log flow - Testing procedures - Manual fixes - Monitoring queries - Quick checklist 🔍 Enhanced Logging: - MailQueue::init() logs hook registration - sendNow() logs all arguments and types - Handles both string and array arguments - Checks database for missing options - Logs wp_mail() result - Logs WooEmailOverride disable/enable 🎯 Usage: 1. Visit check-settings.php - verify configuration 2. Visit test-email-direct.php - test email flow 3. Check debug.log for detailed flow 4. Follow EMAIL_DEBUGGING_GUIDE.md for troubleshooting 📋 Checklist for User: - [ ] Run check-settings.php - [ ] Run test-email-direct.php - [ ] Check debug.log - [ ] Verify Action Scheduler args - [ ] Check Email Log plugin - [ ] Follow debugging guide
This commit is contained in:
dwindown
343
EMAIL_DEBUGGING_GUIDE.md
Normal file
343
EMAIL_DEBUGGING_GUIDE.md
Normal file
@@ -0,0 +1,343 @@
|
||||
# Email Debugging Guide
|
||||
|
||||
## 🔍 Problem: Emails Not Sending
|
||||
|
||||
Action Scheduler shows "Complete" but no emails appear in Email Log plugin.
|
||||
|
||||
## 📋 Diagnostic Tools
|
||||
|
||||
### 1. Check Settings
|
||||
```
|
||||
Visit: /wp-content/plugins/woonoow/check-settings.php
|
||||
```
|
||||
This shows:
|
||||
- Notification system mode
|
||||
- Email channel status
|
||||
- Event configuration
|
||||
- Template configuration
|
||||
- Hook registration status
|
||||
- Action Scheduler stats
|
||||
- Queued emails
|
||||
|
||||
### 2. Test Email Flow
|
||||
```
|
||||
Visit: /wp-content/plugins/woonoow/test-email-flow.php
|
||||
```
|
||||
Interactive dashboard with:
|
||||
- System status
|
||||
- Test buttons
|
||||
- Queue viewer
|
||||
- Action Scheduler monitor
|
||||
|
||||
### 3. Direct Email Test
|
||||
```
|
||||
Visit: /wp-content/plugins/woonoow/test-email-direct.php
|
||||
```
|
||||
Or via WP-CLI:
|
||||
```bash
|
||||
wp eval-file wp-content/plugins/woonoow/test-email-direct.php
|
||||
```
|
||||
|
||||
This:
|
||||
- Queues a test email
|
||||
- Manually triggers sendNow()
|
||||
- Tests wp_mail() directly
|
||||
- Shows detailed output
|
||||
|
||||
## 🔬 Debug Logs to Check
|
||||
|
||||
Enable debug logging in `wp-config.php`:
|
||||
```php
|
||||
define('WP_DEBUG', true);
|
||||
define('WP_DEBUG_LOG', true);
|
||||
define('WP_DEBUG_DISPLAY', false);
|
||||
```
|
||||
|
||||
Then check `/wp-content/debug.log` for:
|
||||
|
||||
### Expected Log Flow:
|
||||
|
||||
```
|
||||
[EmailManager] send_order_processing_email triggered for order #123
|
||||
[EmailManager] Sending order_processing email for order #123
|
||||
[EmailManager] send_email called - Event: order_processing, Recipient: customer
|
||||
[EmailManager] Email rendered successfully - To: customer@example.com, Subject: Order Processing
|
||||
[EmailManager] wp_mail called - Result: success
|
||||
[WooNooW MailQueue] Queued email ID: woonoow_mail_xxx_123456
|
||||
[WooNooW MailQueue] Hook registered: woonoow/mail/send -> MailQueue::sendNow
|
||||
[WooNooW MailQueue] sendNow() called with args: Array(...)
|
||||
[WooNooW MailQueue] email_id type: string
|
||||
[WooNooW MailQueue] email_id value: 'woonoow_mail_xxx_123456'
|
||||
[WooNooW MailQueue] Processing email_id: woonoow_mail_xxx_123456
|
||||
[WooNooW MailQueue] Payload retrieved - To: customer@example.com, Subject: Order Processing
|
||||
[WooNooW MailQueue] Disabling WooEmailOverride to prevent loop
|
||||
[WooNooW MailQueue] Calling wp_mail() now...
|
||||
[WooNooW MailQueue] wp_mail() returned: TRUE (success)
|
||||
[WooNooW MailQueue] Re-enabling WooEmailOverride
|
||||
[WooNooW MailQueue] Sent and deleted email ID: woonoow_mail_xxx_123456
|
||||
```
|
||||
|
||||
## 🐛 Common Issues & Solutions
|
||||
|
||||
### Issue 1: No logs at all
|
||||
**Symptom:** No `[EmailManager]` logs when order status changes
|
||||
|
||||
**Cause:** Hooks not firing or EmailManager not initialized
|
||||
|
||||
**Solution:**
|
||||
1. Check `includes/Core/Bootstrap.php` - ensure `EmailManager::instance()` is called
|
||||
2. Check WooCommerce is active
|
||||
3. Check order status is actually changing
|
||||
|
||||
**Test:**
|
||||
```php
|
||||
// Add to functions.php temporarily
|
||||
add_action('woocommerce_order_status_changed', function($order_id, $old_status, $new_status) {
|
||||
error_log("Order #$order_id status changed: $old_status -> $new_status");
|
||||
}, 10, 3);
|
||||
```
|
||||
|
||||
### Issue 2: "order_processing email is disabled in settings"
|
||||
**Symptom:** Log shows event is disabled
|
||||
|
||||
**Cause:** Event not enabled in notification settings
|
||||
|
||||
**Solution:**
|
||||
1. Visit: WooNooW > Notifications
|
||||
2. Find "Order Processing" event
|
||||
3. Enable "Email" channel
|
||||
4. Save settings
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
wp option get woonoow_notification_settings --format=json
|
||||
```
|
||||
|
||||
### Issue 3: "Email rendering failed"
|
||||
**Symptom:** `[EmailManager] Email rendering failed for event: order_processing`
|
||||
|
||||
**Cause:** Template not configured or invalid
|
||||
|
||||
**Solution:**
|
||||
1. Visit: WooNooW > Email Templates
|
||||
2. Configure template for "order_processing"
|
||||
3. Add subject and content
|
||||
4. Save template
|
||||
|
||||
### Issue 4: sendNow() never called
|
||||
**Symptom:** Action Scheduler shows "Complete" but no `[WooNooW MailQueue] sendNow()` logs
|
||||
|
||||
**Cause:** Hook not registered or Action Scheduler passing wrong arguments
|
||||
|
||||
**Solution:**
|
||||
1. Check `[WooNooW MailQueue] Hook registered` appears in logs
|
||||
2. If not, check `includes/Core/Bootstrap.php` - ensure `MailQueue::init()` is called
|
||||
3. Check Action Scheduler arguments in database:
|
||||
```sql
|
||||
SELECT action_id, hook, args, status
|
||||
FROM wp_actionscheduler_actions
|
||||
WHERE hook = 'woonoow/mail/send'
|
||||
ORDER BY action_id DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
### Issue 5: sendNow() called but no email_id
|
||||
**Symptom:** `[WooNooW MailQueue] ERROR: No email_id provided`
|
||||
|
||||
**Cause:** Action Scheduler passing empty or wrong arguments
|
||||
|
||||
**Check logs for:**
|
||||
```
|
||||
[WooNooW MailQueue] email_id type: NULL
|
||||
[WooNooW MailQueue] email_id value: NULL
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
The code now handles both string and array arguments. If still failing, check Action Scheduler args format.
|
||||
|
||||
### Issue 6: Payload not found in wp_options
|
||||
**Symptom:** `[WooNooW MailQueue] ERROR: Email payload not found for ID: xxx`
|
||||
|
||||
**Cause:** Option was deleted before sendNow() ran, or never created
|
||||
|
||||
**Solution:**
|
||||
1. Check if email was queued: `[WooNooW MailQueue] Queued email ID: xxx`
|
||||
2. Check database:
|
||||
```sql
|
||||
SELECT option_name, option_value
|
||||
FROM wp_options
|
||||
WHERE option_name LIKE 'woonoow_mail_%';
|
||||
```
|
||||
3. If missing, check `MailQueue::enqueue()` is being called
|
||||
|
||||
### Issue 7: wp_mail() returns FALSE
|
||||
**Symptom:** `[WooNooW MailQueue] wp_mail() returned: FALSE (failed)`
|
||||
|
||||
**Cause:** SMTP configuration issue, not a plugin issue
|
||||
|
||||
**Solution:**
|
||||
1. Test wp_mail() directly:
|
||||
```php
|
||||
wp_mail('test@example.com', 'Test', 'Test message');
|
||||
```
|
||||
2. Check SMTP plugin configuration
|
||||
3. Check server mail logs
|
||||
4. Use Email Log plugin to see error messages
|
||||
|
||||
### Issue 8: Notification system mode is "woocommerce"
|
||||
**Symptom:** No WooNooW emails sent, WooCommerce default emails sent instead
|
||||
|
||||
**Cause:** Global toggle set to use WooCommerce emails
|
||||
|
||||
**Solution:**
|
||||
1. Visit: WooNooW > Settings
|
||||
2. Find "Notification System Mode"
|
||||
3. Set to "WooNooW"
|
||||
4. Save
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
wp option get woonoow_notification_system_mode
|
||||
# Should return: woonoow
|
||||
```
|
||||
|
||||
## 🧪 Testing Procedure
|
||||
|
||||
### Step 1: Check Configuration
|
||||
```
|
||||
Visit: /wp-content/plugins/woonoow/check-settings.php
|
||||
```
|
||||
Ensure:
|
||||
- ✅ System mode = "woonoow"
|
||||
- ✅ Email channel = enabled
|
||||
- ✅ Events have email enabled
|
||||
- ✅ Hooks are registered
|
||||
|
||||
### Step 2: Test Direct Email
|
||||
```
|
||||
Visit: /wp-content/plugins/woonoow/test-email-direct.php
|
||||
```
|
||||
This will:
|
||||
1. Queue a test email
|
||||
2. Manually trigger sendNow()
|
||||
3. Test wp_mail() directly
|
||||
|
||||
Check:
|
||||
- ✅ Email appears in Email Log plugin
|
||||
- ✅ Email received in inbox
|
||||
- ✅ Debug logs show full flow
|
||||
|
||||
### Step 3: Test Order Email
|
||||
1. Create a test order
|
||||
2. Change status to "Processing"
|
||||
3. Check debug logs for full flow
|
||||
4. Check Email Log plugin
|
||||
5. Check inbox
|
||||
|
||||
### Step 4: Monitor Action Scheduler
|
||||
```
|
||||
Visit: /wp-admin/admin.php?page=wc-status&tab=action-scheduler
|
||||
```
|
||||
Filter by hook: `woonoow/mail/send`
|
||||
|
||||
Check:
|
||||
- ✅ Actions are created
|
||||
- ✅ Actions complete successfully
|
||||
- ✅ No failed actions
|
||||
- ✅ Args contain email_id
|
||||
|
||||
## 🔧 Manual Fixes
|
||||
|
||||
### Reset Notification Settings
|
||||
```bash
|
||||
wp option delete woonoow_notification_settings
|
||||
wp option delete woonoow_email_templates
|
||||
wp option delete woonoow_notification_system_mode
|
||||
```
|
||||
Then reconfigure in admin.
|
||||
|
||||
### Clear Email Queue
|
||||
```bash
|
||||
wp option list --search='woonoow_mail_*' --format=ids | xargs -I % wp option delete %
|
||||
```
|
||||
|
||||
### Clear Action Scheduler Queue
|
||||
```bash
|
||||
wp action-scheduler clean --hooks=woonoow/mail/send
|
||||
```
|
||||
|
||||
### Force Process Queue
|
||||
```php
|
||||
// Add to functions.php temporarily
|
||||
add_action('init', function() {
|
||||
if (function_exists('as_run_queue')) {
|
||||
as_run_queue();
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
### Check Email Queue Size
|
||||
```sql
|
||||
SELECT COUNT(*) as queued_emails
|
||||
FROM wp_options
|
||||
WHERE option_name LIKE 'woonoow_mail_%';
|
||||
```
|
||||
|
||||
### Check Action Scheduler Stats
|
||||
```sql
|
||||
SELECT status, COUNT(*) as count
|
||||
FROM wp_actionscheduler_actions
|
||||
WHERE hook = 'woonoow/mail/send'
|
||||
GROUP BY status;
|
||||
```
|
||||
|
||||
### Recent Email Activity
|
||||
```bash
|
||||
tail -f /path/to/wp-content/debug.log | grep -E '\[EmailManager\]|\[WooNooW MailQueue\]'
|
||||
```
|
||||
|
||||
## 🎯 Quick Checklist
|
||||
|
||||
Before reporting an issue, verify:
|
||||
|
||||
- [ ] WP_DEBUG enabled and logs checked
|
||||
- [ ] Notification system mode = "woonoow"
|
||||
- [ ] Email channel globally enabled
|
||||
- [ ] Specific event has email enabled
|
||||
- [ ] Email template configured for event
|
||||
- [ ] MailQueue hook registered (check logs)
|
||||
- [ ] Action Scheduler available and working
|
||||
- [ ] SMTP configured and wp_mail() works
|
||||
- [ ] Email Log plugin installed to monitor
|
||||
- [ ] Ran check-settings.php
|
||||
- [ ] Ran test-email-direct.php
|
||||
- [ ] Checked debug logs for full flow
|
||||
|
||||
## 📝 Reporting Issues
|
||||
|
||||
When reporting email issues, provide:
|
||||
|
||||
1. Output of `check-settings.php`
|
||||
2. Output of `test-email-direct.php`
|
||||
3. Debug log excerpt (last 100 lines with email-related entries)
|
||||
4. Action Scheduler screenshot (filtered by woonoow/mail/send)
|
||||
5. Email Log plugin screenshot
|
||||
6. Steps to reproduce
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
If all diagnostics pass but emails still not sending:
|
||||
|
||||
1. Check server mail logs
|
||||
2. Check SMTP relay logs
|
||||
3. Check spam folder
|
||||
4. Test with different email address
|
||||
5. Disable other email plugins temporarily
|
||||
6. Check WordPress mail configuration
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-18
|
||||
**Version:** 1.0
|
||||
Reference in New Issue
Block a user