From 7a967c3399fbb26531b10f05cc294b413dbc8944 Mon Sep 17 00:00:00 2001 From: dwindown Date: Sun, 16 Nov 2025 12:47:08 +0700 Subject: [PATCH] docs: Add comprehensive troubleshooting guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 📝 Created TROUBLESHOOTING.md: - Quick diagnosis steps - Common issues with solutions - Verification procedures - Emergency rollback guide - Help gathering checklist - Prevention tips 🎯 Covers All Issues: 1. Blank page in WP-Admin - Files not found (404) - Wrong extraction path - Dev mode enabled 2. API 500 errors (namespace) 3. WordPress media not loading 4. Changes not reflecting (caches) 5. File permissions ✅ Step-by-Step Solutions: - Clear instructions - Copy-paste commands - Expected outputs - Verification steps 🚀 Quick Reference: - Installation checker usage - Cache clearing commands - File structure verification - API/asset testing - Error log locations --- TROUBLESHOOTING.md | 340 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 340 insertions(+) create mode 100644 TROUBLESHOOTING.md diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..96c6f65 --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,340 @@ +# Troubleshooting Guide + +## Quick Diagnosis + +### Step 1: Run Installation Checker +Upload `check-installation.php` to your server and visit: +``` +https://yoursite.com/wp-content/plugins/woonoow/check-installation.php +``` + +This will show you exactly what's wrong. + +--- + +## Common Issues + +### Issue 1: Blank Page in WP-Admin + +**Symptoms:** +- Blank white page when visiting `/wp-admin/admin.php?page=woonoow` +- Or shows "Please Configure Marketing Setup first" +- No SPA loads + +**Diagnosis:** +1. Open browser console (F12) +2. Check Network tab +3. Look for `app.js` and `app.css` + +**Possible Causes & Solutions:** + +#### A. Files Not Found (404) +``` +❌ admin-spa/dist/app.js → 404 Not Found +❌ admin-spa/dist/app.css → 404 Not Found +``` + +**Solution:** +```bash +# The dist files are missing! +# Re-extract the zip file: +cd /path/to/wp-content/plugins +rm -rf woonoow +unzip woonoow.zip + +# Verify files exist: +ls -la woonoow/admin-spa/dist/ +# Should show: app.js (2.4MB) and app.css (70KB) +``` + +#### B. Wrong Extraction Path +If you extracted into `plugins/woonoow/woonoow/`, the paths will be wrong. + +**Solution:** +```bash +# Correct structure: +wp-content/plugins/woonoow/woonoow.php ✓ +wp-content/plugins/woonoow/admin-spa/dist/app.js ✓ + +# Wrong structure: +wp-content/plugins/woonoow/woonoow/woonoow.php ✗ +wp-content/plugins/woonoow/woonoow/admin-spa/dist/app.js ✗ + +# Fix: +cd /path/to/wp-content/plugins +rm -rf woonoow +unzip woonoow.zip +# This creates: plugins/woonoow/ (correct!) +``` + +#### C. Dev Mode Enabled +``` +❌ Trying to load from localhost:5173 +``` + +**Solution:** +Edit `wp-config.php` and remove or set to false: +```php +// Remove this line: +define('WOONOOW_ADMIN_DEV', true); + +// Or set to false: +define('WOONOOW_ADMIN_DEV', false); +``` + +Then clear caches: +```bash +php -r "opcache_reset();" +wp cache flush +``` + +--- + +### Issue 2: API 500 Errors + +**Symptoms:** +- All API endpoints return 500 +- Console shows: "Internal Server Error" +- Error log: `Class "WooNooWAPIPaymentsController" not found` + +**Cause:** +Namespace case mismatch (old code) + +**Solution:** +```bash +# Check if you have the fix: +grep "use WooNooW" includes/Api/Routes.php + +# Should show (lowercase 'i'): +# use WooNooW\Api\PaymentsController; + +# If it shows (uppercase 'I'): +# use WooNooW\API\PaymentsController; +# Then you need to update! + +# Update: +git pull origin main +# Or re-upload the latest zip + +# Clear caches: +php -r "opcache_reset();" +wp cache flush +``` + +--- + +### Issue 3: WordPress Media Not Loading (Standalone) + +**Symptoms:** +- Error: "WordPress Media library is not loaded" +- "Choose from Media Library" button doesn't work +- Only in standalone mode (`/admin`) + +**Cause:** +Missing wp.media scripts + +**Solution:** +Already fixed in latest code. Update: +```bash +git pull origin main +# Or re-upload the latest zip + +php -r "opcache_reset();" +``` + +--- + +### Issue 4: Changes Not Reflecting + +**Symptoms:** +- Uploaded new code but still seeing old errors +- Fixed files but issues persist + +**Cause:** +Multiple cache layers + +**Solution:** +```bash +# 1. Clear PHP OPcache (MOST IMPORTANT!) +php -r "opcache_reset();" + +# Or visit: +# https://yoursite.com/wp-content/plugins/woonoow/check-installation.php?action=clear_opcache + +# 2. Clear WordPress object cache +wp cache flush + +# 3. Restart PHP-FPM (if above doesn't work) +sudo systemctl restart php8.1-fpm +# or +sudo systemctl restart php-fpm + +# 4. Clear browser cache +# Hard refresh: Ctrl+Shift+R (Windows/Linux) +# Hard refresh: Cmd+Shift+R (Mac) +``` + +--- + +### Issue 5: File Permissions + +**Symptoms:** +- 403 Forbidden errors +- Can't access files + +**Solution:** +```bash +cd /path/to/wp-content/plugins/woonoow + +# Set correct permissions: +find . -type f -exec chmod 644 {} \; +find . -type d -exec chmod 755 {} \; + +# Verify: +ls -la admin-spa/dist/ +# Should show: -rw-r--r-- (644) for files +``` + +--- + +## Verification Steps + +After fixing, verify everything works: + +### 1. Check Files +```bash +cd /path/to/wp-content/plugins/woonoow + +# These files MUST exist: +ls -lh woonoow.php # Main plugin file +ls -lh includes/Admin/Assets.php # Assets handler +ls -lh includes/Api/Routes.php # API routes +ls -lh admin-spa/dist/app.js # SPA JS (2.4MB) +ls -lh admin-spa/dist/app.css # SPA CSS (70KB) +``` + +### 2. Test API +```bash +curl -I https://yoursite.com/wp-json/woonoow/v1/store/settings + +# Should return: +# HTTP/2 200 OK +``` + +### 3. Test Assets +```bash +curl -I https://yoursite.com/wp-content/plugins/woonoow/admin-spa/dist/app.js + +# Should return: +# HTTP/2 200 OK +# Content-Length: 2489867 +``` + +### 4. Test WP-Admin +Visit: `https://yoursite.com/wp-admin/admin.php?page=woonoow` + +**Should see:** +- ✓ WooNooW dashboard loads +- ✓ No console errors +- ✓ Navigation works + +**Should NOT see:** +- ✗ Blank page +- ✗ "Please Configure Marketing Setup" +- ✗ Errors about localhost:5173 + +### 5. Test Standalone +Visit: `https://yoursite.com/admin` + +**Should see:** +- ✓ Standalone admin loads +- ✓ Login page (if not logged in) +- ✓ Dashboard (if logged in) + +--- + +## Emergency Rollback + +If everything breaks: + +```bash +# 1. Deactivate plugin +wp plugin deactivate woonoow + +# 2. Remove plugin +rm -rf /path/to/wp-content/plugins/woonoow + +# 3. Re-upload fresh zip +unzip woonoow.zip -d /path/to/wp-content/plugins/ + +# 4. Reactivate +wp plugin activate woonoow + +# 5. Clear all caches +php -r "opcache_reset();" +wp cache flush +``` + +--- + +## Getting Help + +If issues persist, gather this info: + +1. **Run installation checker:** + ``` + https://yoursite.com/wp-content/plugins/woonoow/check-installation.php + ``` + Take screenshot of results + +2. **Check error logs:** + ```bash + tail -50 /path/to/wp-content/debug.log + tail -50 /var/log/php-fpm/error.log + ``` + +3. **Browser console:** + - Open DevTools (F12) + - Go to Console tab + - Take screenshot of errors + +4. **Network tab:** + - Open DevTools (F12) + - Go to Network tab + - Reload page + - Take screenshot showing failed requests + +5. **File structure:** + ```bash + ls -la /path/to/wp-content/plugins/woonoow/ + ls -la /path/to/wp-content/plugins/woonoow/admin-spa/dist/ + ``` + +Send all this info when requesting help. + +--- + +## Prevention + +To avoid issues in the future: + +1. **Always clear caches after updates:** + ```bash + php -r "opcache_reset();" + wp cache flush + ``` + +2. **Verify files after extraction:** + ```bash + ls -lh admin-spa/dist/app.js + # Should be ~2.4MB + ``` + +3. **Use installation checker:** + Run it after every deployment + +4. **Keep backups:** + Before updating, backup the working version + +5. **Test in staging first:** + Don't deploy directly to production