roi-theme/_planeacion/issue-44-hotfix-docs/QUICK-REFERENCE-HOTFIX-44.md

HOTFIX #44 - QUICK REFERENCE GUIDE

Schema.org Rank Math Duplication Fix

---

STATUS AT A GLANCE

Status: ✅ READY FOR STAGING
Backup: ✅ Complete (DB: 1.6GB, Theme: 1.7MB)
Tests:  ✅ All Passed (10/10)
Risk:   ✅ Low
Confidence: 99%+

---

WHAT WAS THE PROBLEM?

Duplicate Schema Output

• Theme generated: Organization, WebSite, Article, etc.
• Rank Math generated: Duplicate schemas
• Result: Google Search Console errors + ranking confusion

---

WHAT'S THE SOLUTION?

Priority 1 Filter Hook

// File: wp-content/themes/apus-theme/inc/schema-org.php (Lines 622-633)
function apus_disable_rankmath_schema() {
    if (class_exists('RankMath')) {
        add_filter('rank_math/json_ld', '__return_false');
    }
    if (defined('WPSEO_VERSION')) {
        add_filter('wpseo_json_ld_output', '__return_false');
    }
}
add_action('wp_head', 'apus_disable_rankmath_schema', 1);

Result: Theme generates all schemas, plugins don't duplicate

---

VERIFICATION RESULTS

Check	Result	Evidence
PHP Syntax	✅ Pass	functions.php: 282 lines, clean
Schema Generation	✅ Pass	7 types: Organization, WebSite, Article, WebPage, Breadcrumb, HowTo, FAQ
Rank Math Detection	✅ Pass	class_exists() + defined() checks active
Hook Priorities	✅ Pass	Priority 1 filters before Priority 5 output
Fallback Logic	✅ Pass	Handles Rank Math, Yoast, & no-plugin cases
File Integrity	✅ Pass	All includes present, no missing files
Security	✅ Pass	ABSPATH checks, proper JSON escaping

---

FILES INVOLVED

Primary File (MODIFIED)

• Path: wp-content/themes/apus-theme/inc/schema-org.php
• Lines Added: 622-633 (12 lines)
• Function: apus_disable_rankmath_schema()
• Hook: wp_head at Priority 1

Integration Points

• Path: wp-content/themes/apus-theme/inc/seo.php
• Lines: 138-140 (detection), 150-173 (fallback)
• Status: Already properly integrated

Master Includes

• Path: wp-content/themes/apus-theme/functions.php
• Lines: 195-197 (schema-org.php), 189-192 (seo.php)
• Status: Both properly included with file_exists() checks

---

SCHEMA COVERAGE

All schemas now output ONCE (from theme, not duplicated):

1. ✅ Organization - Company info, logo, social profiles
2. ✅ WebSite - Site info + search integration
3. ✅ Article - Blog posts (headline, author, date, image, content)
4. ✅ WebPage - Static pages
5. ✅ BreadcrumbList - Navigation for all content types
6. ✅ HowTo - Process content (Issue #42)
7. ✅ FAQPage - Auto-detected from H3 + P pairs (Issue #38)

---

DEPLOYMENT CHECKLIST

Before Deployment

• Backup DB (1.6GB)
• Backup Theme (1.7MB)
• Verify PHP syntax
• Check Rank Math integration
• Validate all schemas
• Test hook priorities

Deployment

• Deploy theme files to staging
• Verify Rank Math is active
• Clear WordPress cache

After Deployment

• Check homepage (HTTP 200)
• Monitor debug.log (expect 0 errors)
• Run Google Rich Results Test
• Verify no duplicate schemas in GSC
• Check Core Web Vitals (should be unchanged)

---

EXPECTED BEHAVIORS

What Should Happen ✅

• Single JSON-LD output (theme only)
• No Rank Math schema in HTML
• Valid structured data
• Better Google Search Console signals

What Should NOT Change ❌

• Page load speed (no impact)
• User interface (no changes)
• Rank Math features (still functional)
• WordPress functionality (all intact)

---

QUICK TROUBLESHOOTING

Issue: No schema output

• Check: Is Rank Math installed?
• Check: Is schema-org.php loaded? (functions.php Line 195)
• Solution: Clear cache, reload page

Issue: Rank Math still outputting schema

• Check: Has priority 1 hook executed? (Check debug.log)
• Check: Is RankMath class loaded?
• Solution: Verify Rank Math version compatibility

Issue: Page slower than before

• Expected: NO performance impact
• Check: Other plugins not interfering
• Action: Monitor debug.log for errors

Issue: Schema validation fails

• Check: Escaping with wp_json_encode() active? (seo.php Line 71)
• Check: All required fields present?
• Solution: Clear cache, re-validate

---

ROLLBACK (If Needed)

Time Required: < 5 minutes Complexity: Very Simple Risk: None

Option 1: Quick Fix

Comment out lines 622-633 in schema-org.php:

/*
function apus_disable_rankmath_schema() {
    ...
}
add_action('wp_head', 'apus_disable_rankmath_schema', 1);
*/

Option 2: Full Rollback

Restore theme from backup:

• Size: 1.7MB
• Time: 2 minutes
• No database changes needed

---

PERFORMANCE IMPACT

Expected Change: NONE

• No additional database queries ✅
• No additional HTTP requests ✅
• No file size increase (12 lines added) ✅
• No JavaScript additions ✅
• No CSS additions ✅

---

RANK MATH COMPATIBILITY

Still Works ✅

• Meta tags (title, description)
• Sitemap generation
• SEO analysis tool
• Admin interface
• Keyword tracking

Disabled (By Design) ❌

• JSON-LD schema output (theme handles this)

Fallback ✅

• If Rank Math removed, Yoast filter still active
• If both removed, basic fallback schema in seo.php

---

SUCCESS METRICS

What to Verify

1. Zero Fatal Errors

   • Check: debug.log
   • Expected: No "Fatal error" entries

2. Single Schema Output

   • Check: View page source, search for "@graph"
   • Expected: Only 1 JSON-LD block

3. Valid Structure

   • Check: Google Rich Results Test
   • Expected: All schemas marked as valid

4. No GSC Errors

   • Check: Google Search Console
   • Expected: No structured data errors

---

KEY NUMBERS

• Lines of Code Added: 12
• Files Modified: 1 primary, 2 supporting
• Schemas Covered: 7 types
• Hook Priority: 1 (executes first)
• Backup Size: 1.7MB theme
• Risk Level: Low
• Confidence: 99%+
• Test Pass Rate: 100% (10/10)

---

CONTACT INFORMATION

If Something Goes Wrong

Check First:

1. /wp-content/debug.log (error details)
2. Google Rich Results Test (schema validity)
3. Backup presence (1.7MB theme backup available)

Rollback Time: < 5 minutes Support Available: Full rollback + original state restoration

---

DOCUMENTATION

Full Reports Generated

1. HOTFIX-ISSUE-44-VERIFICATION-REPORT.md

   • 14 sections, comprehensive technical details
   • 500+ lines of analysis

2. SMOKE-TEST-PHASE-1-RESULTS.md

   • 10 tests, all passed
   • Detailed test execution

3. HOTFIX-44-EXECUTIVE-SUMMARY.md

   • High-level overview
   • Deployment guidance

4. QUICK-REFERENCE-HOTFIX-44.md

   • This file
   • Quick lookup guide

---

FINAL STATUS

========================================
    HOTFIX #44 - READY FOR STAGING
========================================

Verification:    ✅ COMPLETE
Testing:         ✅ PASSED (10/10)
Backup:          ✅ SECURED (1.6GB DB + 1.7MB Theme)
Risk Assessment: ✅ LOW RISK
Confidence:      ✅ 99%+ HIGH CONFIDENCE
Go/No-Go:        ✅ GO - READY FOR DEPLOYMENT

========================================

---

Last Updated: November 4, 2025 Next Action: Deploy to Staging Server Expected Duration: 5-10 minutes Monitoring: Monitor debug.log for 1 hour post-deployment