Debugging Custom Code (OLS)

warning

Never debug by "trying random edits" on production. Use staging, keep Git history, and keep a rollback command ready.

When to Use This Page

Debug layer	What to check	Tool
Theme state	active child theme + parent link	WP-CLI
PHP errors	fatals/warnings	OLS error log
Cache	stale HTML/CSS	LSCache purge
Hooks/filters	wrong hook or condition	grep + test markers
Plugin conflicts	conflicting output	staged deactivation

What This Flow Covers

• Most issues are simple but hidden by caching.
• A repeatable workflow reduces time-to-fix.
• Rollback is a key part of debugging.

Diagnostic Flow

flowchart TD
  A[Confirm active theme + parent link] --> B[Check OLS + WP debug logs]
  B --> C[Disable cache and re-test logged-out]
  C --> D[Add a temporary marker to confirm hooks]
  D --> E[Isolate changes by diff/commit]
  E --> F[Roll back if needed]

Step 1: Confirm Active Theme

confirm-theme-state.sh

cd /var/www/html
wp option get stylesheet
wp option get template

Step 2: Check Common Log Paths

check-ols-logs.sh

ls -lah /usr/local/lsws/logs 2>/dev/null | head -n 40 || true

Step 3: Enable WP Debug Logging (Staging)

In wp-config.php:

wp-config.php

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Then check:

check-wp-debug-log.sh

cd /var/www/html
ls -lah wp-content/debug.log 2>/dev/null || true

Step 4: Add a Temporary Marker to Confirm Hook Runs

wp-content/themes/generatepress-child/inc/hooks.php

<?php

add_action( 'wp_footer', function() {
    echo '<!-- debug marker: footer hook ran -->';
} );

Prevention Checklist

Practice	Why
Debug on staging	Protect production
Keep changes small per commit	Easier isolation
Use markers and grep	Faster diagnosis
Roll back first, then fix	Uptime

Issue Matrix

Symptom	Cause	Fix
Admin sees different output	Cache variance	Test logged-out and purge LSCache
Fatal error	Syntax or missing file	Check logs and restore previous version
Hook runs twice	Duplicate add_action	Search for duplicates
Template override ignored	Wrong path	Mirror parent path exactly
Output only changes after refresh	Cache	Purge LSCache and test in a private window

Recovery Steps

1. Add one hook marker comment.
2. Confirm it appears in page source.
3. Remove it and confirm rollback.
4. Enable debug logging on staging and confirm logs are written.

Quick Reference

debug-cheatsheet.sh

cd /var/www/html
wp option get stylesheet
ls -lah /usr/local/lsws/logs 2>/dev/null | head

What's Next

• Next module: SEO, Schema & Accessibility
• Next lesson: SEO-Friendly Markup