Ep.03: WordPress Plugin Theme Compatibility Check – Ensuring Versana is Active

Views: 3

Learn how to add WordPress plugin theme compatibility checking with simple if/else code. Step-by-step guide to detect active themes, show admin notices, and prevent plugin errors for beginners.

Introduction

Welcome to Episode 3 of building the Versana Companion plugin! In Episode 2, we created our basic plugin structure. Now we need to make it smart enough to check if the Versana theme is actually active.

In this episode, you’ll learn WordPress plugin theme compatibility checking using simple if/else statements. No complex code – just straightforward PHP that checks if the right theme is running before your plugin does anything.

Why does this matter? Imagine someone installs your plugin but uses a different theme. Your plugin tries to use Versana-specific features that don’t exist… BOOM! Errors everywhere. Let’s prevent that.

What We’ll Cover

1. Why theme compatibility checking is essential
2. How WordPress stores active theme information
3. Writing a simple theme detection function
4. Showing admin notices to users
5. Stopping plugin features when wrong theme is active
6. Testing all scenarios
7. Handling child themes automatically

Prerequisites

• Completed Episode 2 (basic plugin created)
• WordPress 6.0+ installed
• Versana Companion plugin activated
• Text editor open
• Basic understanding of if/else statements

---

Part 1: Why Check Theme Compatibility?

The Problem We’re Solving

Scenario without theme check:

User installs Versana Companion ✓
User has Astra theme active (not Versana) ✗
Plugin tries to use versana_get_option() ✗
Function doesn't exist ✗
Fatal error appears ✗
Site breaks ✗
User angry ✗
Bad review ✗

Scenario with theme check:

User installs Versana Companion ✓
Plugin checks theme ✓
Wrong theme detected ✓
Shows friendly notice: "Need Versana theme" ✓
Provides link to get theme ✓
Site works fine ✓
User understands ✓
Everyone happy ✓

Real-World Example

// ❌ WITHOUT THEME CHECK (Bad)
function versana_companion_init() {
    // Assumes Versana theme is active
    $layout = versana_get_blog_layout(); // CRASH if Versana not active!
    echo $layout;
}

// ✅ WITH THEME CHECK (Good)
function versana_companion_init() {
    // Check theme first
    if ( ! versana_companion_is_theme_active() ) {
        return; // Stop safely
    }
    
    // Safe to use Versana functions now
    $layout = versana_get_blog_layout();
    echo $layout;
}

---

Part 2: How WordPress Stores Theme Information

Understanding Theme Storage

WordPress stores the active theme name in the database. We can check it with simple WordPress functions.

What WordPress tracks:

Active theme name: "Versana"
Theme folder: "versana"
Parent theme (if child): "Versana" or empty
Theme version: "1.0.0"

The Key WordPress Function

// Get current theme information
$theme = wp_get_theme();

// What this returns:
echo $theme->get('Name');        // "Versana"
echo $theme->get('Version');     // "1.0.0"
echo $theme->get('Template');    // "versana" (folder name)

Simple example:

$theme = wp_get_theme();
echo $theme->get('Name'); 

// If Versana active: Shows "Versana"
// If Astra active: Shows "Astra"
// If Twenty Twenty-Four active: Shows "Twenty Twenty-Four"

---

Part 3: Creating the Theme Check Function

Step 1: Open Your Plugin File

Open versana-companion/versana-companion.php in your text editor.

Step 2: Add the Theme Check Function

Add this function after your constants and before the activation hook:

<?php
/**
 * Plugin Name: Versana Companion
 * Description: Adds demo import and advanced features to Versana theme
 * Version: 1.0.0
 * Author: Your Name
 * Text Domain: versana-companion
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Plugin constants
 */
define( 'VERSANA_COMPANION_VERSION', '1.0.0' );
define( 'VERSANA_COMPANION_PATH', plugin_dir_path( __FILE__ ) );
define( 'VERSANA_COMPANION_URL', plugin_dir_url( __FILE__ ) );

/**
 * Check if Versana theme is active
 * 
 * This function checks if the active theme is Versana
 * or a child theme of Versana.
 * 
 * @return bool True if Versana is active, false otherwise
 */
function versana_companion_is_theme_active() {
    // Get current theme information
    $theme = wp_get_theme();
    
    // Get theme name
    $theme_name = $theme->get('Name');
    
    // Check if theme name is "Versana"
    if ( 'Versana' === $theme_name ) {
        return true; // Versana theme is active!
    }
    
    // Check if it's a child theme of Versana
    $parent_theme = $theme->get('Template');
    if ( 'versana' === $parent_theme ) {
        return true; // Versana child theme is active!
    }
    
    // Neither Versana nor child theme active
    return false;
}

// Rest of your plugin code continues...

Understanding this function line by line:

function versana_companion_is_theme_active() {

• Creates a function we can call anywhere
• Returns true or false
• Descriptive name tells us what it does

    $theme = wp_get_theme();

• Gets information about current theme
• WordPress function, built-in
• Returns theme object with all details

    $theme_name = $theme->get('Name');

• Extracts theme name from object
• Returns: “Versana” or “Astra” or “Twenty Twenty-Four” etc.
• This is display name (what user sees)

    if ( 'Versana' === $theme_name ) {
        return true;
    }

• Checks if name is exactly “Versana”
• If yes, return true (theme is active)
• If no, keep checking

    $parent_theme = $theme->get('Template');
    if ( 'versana' === $parent_theme ) {
        return true;
    }

• Gets parent theme folder name
• Important for child themes
• If parent is “versana”, return true

    return false;

• If neither check passed
• Return false (Versana not active)

Why Check Both Name and Template?

Example scenarios:

// Scenario 1: Versana theme directly active
$theme->get('Name');      // "Versana"
$theme->get('Template');  // "versana"
Result: TRUE ✓

// Scenario 2: Versana child theme active
$theme->get('Name');      // "My Custom Versana"
$theme->get('Template');  // "versana" (parent folder)
Result: TRUE ✓

// Scenario 3: Different theme active
$theme->get('Name');      // "Astra"
$theme->get('Template');  // "astra"
Result: FALSE ✗

---

Part 4: Using the Theme Check Function

Step 3: Check Theme Before Doing Anything

Now let’s use our function. Update your plugin initialization:

/**
 * Initialize plugin only if Versana theme is active
 */
function versana_companion_init() {
    // FIRST: Check if correct theme is active
    if ( ! versana_companion_is_theme_active() ) {
        // Wrong theme! Don't load plugin features
        return;
    }
    
    // If we reach here, Versana theme is active
    // Safe to load plugin features
    
    // For now, just show a success message
    if ( is_admin() ) {
        add_action( 'admin_notices', 'versana_companion_success_notice' );
    }
}
add_action( 'plugins_loaded', 'versana_companion_init' );

/**
 * Success notice - shows when theme is correct
 */
function versana_companion_success_notice() {
    ?>
    <div class="notice notice-success is-dismissible">
        <p>
            <strong>✓ Versana Companion is active and working!</strong>
            Versana theme detected successfully.
        </p>
    </div>
    <?php
}

Understanding the logic:

if ( ! versana_companion_is_theme_active() ) {
    return;
}

This means:

• If theme is NOT active (notice the !)
• Stop right here (return)
• Don’t execute any code below
• Plugin features don’t load
• No errors happen

Breaking down the condition:

// The exclamation mark (!) means "NOT"
!  versana_companion_is_theme_active()

// Read it as: "If NOT theme active"
// Or: "If theme is inactive"

// Same as writing:
if ( versana_companion_is_theme_active() === false ) {
    return;
}

---

Part 5: Adding User-Friendly Error Notice

Step 4: Show Helpful Message for Wrong Theme

Users need to know WHY the plugin won’t work. Let’s add a helpful notice:

/**
 * Initialize plugin
 */
function versana_companion_init() {
    // Check theme compatibility
    if ( ! versana_companion_is_theme_active() ) {
        // Show error notice
        add_action( 'admin_notices', 'versana_companion_theme_error_notice' );
        return; // Stop plugin from loading
    }
    
    // Theme is correct, continue...
    if ( is_admin() ) {
        add_action( 'admin_notices', 'versana_companion_success_notice' );
    }
}
add_action( 'plugins_loaded', 'versana_companion_init' );

/**
 * Theme error notice - shows when wrong theme active
 */
function versana_companion_theme_error_notice() {
    // Get current theme name to show user
    $theme = wp_get_theme();
    $current_theme = $theme->get('Name');
    ?>
    <div class="notice notice-error is-dismissible">
        <p>
            <strong>⚠️ Versana Companion Error:</strong>
            This plugin requires the Versana theme. 
            You currently have <strong><?php echo esc_html( $current_theme ); ?></strong> active.
        </p>
        <p>
            <a href="<?php echo admin_url('themes.php'); ?>" class="button button-primary">
                Go to Themes
            </a>
            <a href="https://wordpress.org/themes/versana/" class="button" target="_blank">
                Get Versana Theme
            </a>
        </p>
    </div>
    <?php
}

/**
 * Success notice
 */
function versana_companion_success_notice() {
    ?>
    <div class="notice notice-success is-dismissible">
        <p>
            <strong>✓ Versana Companion is active!</strong>
            Theme compatibility confirmed.
        </p>
    </div>
    <?php
}

Understanding the error notice:

$theme = wp_get_theme();
$current_theme = $theme->get('Name');

• Gets current theme name
• Shows user what they have active
• Example: “Astra”, “Twenty Twenty-Four”, etc.

<div class="notice notice-error is-dismissible">

• notice = WordPress admin notice styling
• notice-error = Red background (error color)
• is-dismissible = Shows X button to close

<?php echo esc_html( $current_theme ); ?>

• esc_html() = Security function
• Prevents malicious code from running
• Always escape output!

<a href="<?php echo admin_url('themes.php'); ?>" class="button button-primary">
    Go to Themes
</a>

• Creates button-styled link
• Links to WordPress themes page
• User can easily switch themes

<a href="https://wordpress.org/themes/versana/" class="button" target="_blank">
    Get Versana Theme
</a>

• Links to Versana on WordPress.org
• Opens in new tab (target="_blank")
• User can download Versana theme

---

Part 6: Complete Updated Plugin Code

Your Full versana-companion.php File

Here’s everything together:

<?php
/**
 * Plugin Name: Versana Companion
 * Description: Adds demo import and advanced features to Versana theme
 * Version: 1.0.0
 * Author: Your Name
 * Author URI: https://yourwebsite.com
 * License: GPL v2 or later
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: versana-companion
 * Domain Path: /languages
 * Requires at least: 6.0
 * Requires PHP: 7.4
 */

// Security check - prevent direct access
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Plugin constants
 */
define( 'VERSANA_COMPANION_VERSION', '1.0.0' );
define( 'VERSANA_COMPANION_PATH', plugin_dir_path( __FILE__ ) );
define( 'VERSANA_COMPANION_URL', plugin_dir_url( __FILE__ ) );

/**
 * Check if Versana theme is active
 * 
 * Checks both direct theme activation and child theme scenarios
 * 
 * @return bool True if Versana active, false otherwise
 */
function versana_companion_is_theme_active() {
    // Get current theme
    $theme = wp_get_theme();
    
    // Check direct Versana activation
    if ( 'Versana' === $theme->get('Name') ) {
        return true;
    }
    
    // Check if child theme of Versana
    if ( 'versana' === $theme->get('Template') ) {
        return true;
    }
    
    // Versana not active
    return false;
}

/**
 * Initialize plugin
 * 
 * Runs after all plugins are loaded
 */
function versana_companion_init() {
    // First: Check theme compatibility
    if ( ! versana_companion_is_theme_active() ) {
        // Wrong theme - show error and stop
        add_action( 'admin_notices', 'versana_companion_theme_error_notice' );
        return;
    }
    
    // Theme is correct - continue initialization
    if ( is_admin() ) {
        add_action( 'admin_notices', 'versana_companion_success_notice' );
    }
    
    // Future: Plugin features will be loaded here
}
add_action( 'plugins_loaded', 'versana_companion_init' );

/**
 * Error notice for wrong theme
 */
function versana_companion_theme_error_notice() {
    // Get current theme name
    $theme = wp_get_theme();
    $current_theme = $theme->get('Name');
    ?>
    <div class="notice notice-error is-dismissible">
        <p>
            <strong>⚠️ Versana Companion Error:</strong>
            This plugin requires the Versana theme. 
            You currently have <strong><?php echo esc_html( $current_theme ); ?></strong> active.
        </p>
        <p>
            <a href="<?php echo admin_url('themes.php'); ?>" class="button button-primary">
                Go to Themes
            </a>
            <a href="https://wordpress.org/themes/versana/" class="button" target="_blank">
                Get Versana Theme
            </a>
        </p>
    </div>
    <?php
}

/**
 * Success notice for correct theme
 */
function versana_companion_success_notice() {
    ?>
    <div class="notice notice-success is-dismissible">
        <p>
            <strong>✓ Versana Companion is active!</strong>
            Theme compatibility confirmed.
        </p>
    </div>
    <?php
}

/**
 * Plugin activation
 */
function versana_companion_activate() {
    add_option( 'versana_companion_version', VERSANA_COMPANION_VERSION );
    add_option( 'versana_companion_activated', current_time( 'mysql' ) );
}
register_activation_hook( __FILE__, 'versana_companion_activate' );

/**
 * Plugin deactivation
 */
function versana_companion_deactivate() {
    // Cleanup if needed
}
register_deactivation_hook( __FILE__, 'versana_companion_deactivate' );

/**
 * Load text domain for translations
 */
function versana_companion_load_textdomain() {
    load_plugin_textdomain(
        'versana-companion',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
}
add_action( 'plugins_loaded', 'versana_companion_load_textdomain' );

File saved! Now let’s test it.

---

Part 7: Testing Theme Compatibility Check

Test Scenario 1: Wrong Theme Active (Most Important!)

Setup:

1. Make sure Astra (or any theme except Versana) is active
2. Versana Companion plugin is active
3. Go to WordPress Dashboard

Expected Result:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ Versana Companion Error: This plugin requires 
the Versana theme. You currently have Astra active.

[Go to Themes]  [Get Versana Theme]           ✕
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What you should see:

• ✓ Red error notice at top of admin
• ✓ Shows YOUR current theme name (not “Astra” if different)
• ✓ Two buttons: “Go to Themes” and “Get Versana Theme”
• ✓ X button to dismiss notice (but it comes back)
• ✓ No other errors on page
• ✓ Site still works fine

What the buttons do:

• “Go to Themes” → Takes you to Appearance → Themes
• “Get Versana Theme” → Opens WordPress.org in new tab

Test Scenario 2: Correct Theme Active

Setup:

1. Activate Versana theme (Appearance → Themes → Versana → Activate)
2. Keep Versana Companion plugin active
3. Go to WordPress Dashboard

Expected Result:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Versana Companion is active! Theme 
compatibility confirmed.                     ✕
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What you should see:

• ✓ Green success notice
• ✓ Checkmark icon
• ✓ Positive confirmation message
• ✓ X button to dismiss
• ✓ No errors

Test Scenario 3: Switch Themes While Plugin Active

Setup:

1. Start with Versana active (green notice showing)
2. Go to Appearance → Themes
3. Activate a different theme (Astra, Twenty Twenty-Four, etc.)
4. Go back to Dashboard

Expected Result:

• ✓ Red error notice appears immediately
• ✓ Shows new theme name
• ✓ Plugin stops working (safely)
• ✓ No fatal errors
• ✓ Site continues working

Test Scenario 4: Child Theme of Versana

First, create a simple child theme:

1. Create folder: wp-content/themes/versana-child/
2. Create file: versana-child/style.css
3. Add this content:

/*
Theme Name: Versana Child
Template: versana
Version: 1.0.0
*/

4. Activate Versana Child theme
5. Check plugin notice

Expected Result:

• ✓ Green success notice shows
• ✓ Plugin recognizes child theme
• ✓ No errors
• ✓ Everything works

This proves our child theme detection works!

---

Part 8: Understanding What We Built

How the Flow Works

Visual Flow Diagram:

User loads WordPress page
         ↓
WordPress loads all plugins
         ↓
Our plugin hook: plugins_loaded
         ↓
versana_companion_init() runs
         ↓
Checks: Is Versana active?
         ↓
    ┌────┴────┐
    NO        YES
    ↓          ↓
Show error   Show success
notice       notice
    ↓          ↓
Stop here    Continue
(return)     loading features
             ↓
         Plugin works!

The If/Else Logic Explained

if ( ! versana_companion_is_theme_active() ) {
    // Code here runs if theme is WRONG
    add_action( 'admin_notices', 'versana_companion_theme_error_notice' );
    return;
}

// Code here runs if theme is RIGHT
add_action( 'admin_notices', 'versana_companion_success_notice' );

In plain English:

IF theme is NOT active
    THEN show error
    AND stop here
ELSE (theme must be active)
    Show success
    Continue with plugin

Why Return Early?

if ( ! versana_companion_is_theme_active() ) {
    return; // STOPS HERE - very important!
}

// This code only runs if return didn't happen
// Which means theme must be active

The return statement is like a STOP sign. Everything after it is skipped.

---

Part 9: Common Questions Answered

Q1: Why check theme name AND template?

Answer: To support child themes!

// Parent theme active:
Name: "Versana"      ✓ Caught by name check
Template: "versana"  ✓ Also matches

// Child theme active:
Name: "My Versana"   ✗ Doesn't match name
Template: "versana"  ✓ Matches template check!

Without template check, child themes wouldn’t work!

Q2: What if user renames Versana theme folder?

Answer: Our check still works!

// Even if folder renamed to "versana-modified"
$theme->get('Name');     // Still "Versana" (from style.css)
$theme->get('Template'); // Still "versana" (parent reference)

The template check uses the parent theme’s folder name, which can’t change without breaking the child theme.

Q3: Do I need to check on EVERY page load?

Answer: Yes, because theme can change anytime.

User visits page → Theme check runs → All good
User switches theme → Next page load → Check runs → Wrong theme → Error shows

It’s a lightweight check (just reads one database value), so performance impact is minimal.

Q4: Why not just deactivate the plugin automatically?

Answer: Too aggressive!

❌ Auto-deactivate:
- Assumes user made mistake
- User loses settings
- Confusing behavior
- Against WordPress guidelines

✅ Show notice:
- User stays in control
- Clear explanation
- Helpful actions
- Professional approach

Q5: What about multisite?

Answer: Works automatically!

Each site in a multisite network can have a different theme. Our check runs per-site, so it works correctly:

Site 1: Versana active → Plugin works
Site 2: Astra active → Plugin shows error
Site 3: Versana Child active → Plugin works

---

Part 10: What’s Next

In This Episode, We Built:

✅ Theme detection function (simple if/else) ✅ Error notice for wrong theme (red box) ✅ Success notice for right theme (green box) ✅ Automatic child theme support ✅ Safe plugin stopping (no crashes) ✅ User-friendly error messages ✅ Helpful action buttons

Your Plugin Now:

• ✓ Detects active theme correctly
• ✓ Shows appropriate notices
• ✓ Stops safely if wrong theme
• ✓ Works with parent and child themes
• ✓ Provides helpful guidance to users
• ✓ Never crashes the site

Coming in Episode 4:

Admin Settings Page – We’ll create:

• Settings menu in WordPress admin
• HTML form with fields
• Save/load settings
• Organize settings in tabs
• All with simple HTML and PHP (no complex frameworks)

---

Conclusion

Congratulations! You’ve successfully added WordPress plugin theme compatibility checking to Versana Companion. Your plugin is now smart enough to detect themes and guide users appropriately.

What We Learned

Technical Skills:

• ✅ Using wp_get_theme() function
• ✅ Checking theme name and template
• ✅ Writing simple if/else conditions
• ✅ Creating admin notices (error and success)
• ✅ Stopping code execution safely with return
• ✅ Escaping output with esc_html()

Best Practices:

• ✅ Always check dependencies before using them
• ✅ Fail gracefully with helpful messages
• ✅ Support child themes automatically
• ✅ Provide actionable solutions
• ✅ Test all scenarios thoroughly

Key Takeaways

For WordPress plugin theme compatibility:

1. Check Early – Before loading any features
2. Check Always – On every page load
3. Support Children – Check both name and template
4. Show, Don’t Break – Display notices, don’t crash
5. Help Users – Provide clear next steps
6. Test Everything – All theme scenarios

Testing Checklist

Before Episode 4, verify:

• [ ] Error notice shows with wrong theme
• [ ] Success notice shows with Versana
• [ ] Buttons in error notice work
• [ ] Child themes are recognized
• [ ] No PHP errors in any scenario
• [ ] Notice is dismissible (X button works)
• [ ] Theme switching triggers appropriate notice
• [ ] No fatal errors occur

Your Updated File Structure

versana-companion/
├── versana-companion.php    ✅ Updated with theme checking
├── readme.txt               ✅ From Episode 2
├── includes/                ✅ Empty (for future)
├── admin/                   ✅ Empty (for Episode 4)
└── assets/                  ✅ Empty (for future)

---

Troubleshooting Common Issues

Issue 1: Notice Shows Even with Versana Active

Check:

// Verify theme name spelling
$theme = wp_get_theme();
echo $theme->get('Name'); // Should show exactly "Versana"

// Check for extra spaces or different cases
if ( 'Versana' === $theme->get('Name') ) { // Exact match

Solution:

• Theme name must be exactly “Versana” (capital V)
• Check your theme’s style.css header
• Ensure no extra spaces

Issue 2: Notice Doesn’t Appear

Check:

// Make sure hook is firing
add_action( 'plugins_loaded', 'versana_companion_init' );

// Verify function exists
if ( function_exists( 'versana_companion_init' ) ) {
    echo "Function exists!";
}

Solution:

• Syntax error preventing loading
• Check for missing semicolons
• Look in debug.log for PHP errors

Issue 3: Both Notices Show at Same Time

Problem: You see both red and green notices.

Cause: Logic error in if/else

Solution:

// Make sure return statement exists
if ( ! versana_companion_is_theme_active() ) {
    add_action( 'admin_notices', 'versana_companion_theme_error_notice' );
    return; // ← This MUST be here!
}

// Success notice only reaches here if return didn't happen
add_action( 'admin_notices', 'versana_companion_success_notice' );

Issue 4: Child Theme Not Recognized

Check your child theme’s style.css:

/*
Theme Name: Versana Child
Template: versana    ← Must be lowercase "versana"
*/

Common mistake:

/*
Template: Versana    ← Wrong! Capital V won't work
*/

Solution: Template must match parent folder name exactly (lowercase).

---

Frequently Asked Questions

Q: Does this check slow down my site? A: No. It runs once per page load and is just a database read. Negligible performance impact.

Q: Can I remove the success notice after testing? A: Yes! Once you verify it works, you can remove or comment out the success notice.

Q: What if someone has Versana but an old version? A: We’ll add version checking in a future episode. For now, any Versana version is accepted.

Q: Should I check theme on activation too? A: Optional. Current approach (checking on every load) is sufficient and catches theme changes.

Q: Can I customize the error message? A: Yes! Edit the text in versana_companion_theme_error_notice() function.

Q: What if WordPress adds a new theme function? A: Our method uses stable WordPress core functions that won’t change.

Q: Does this work with WordPress 5.x? A: Yes! The functions we use have been in WordPress for many versions.

Q: How do I test without switching themes constantly? A: You can temporarily modify the check to test different scenarios, then restore it.

---

Next Episode Preview

Episode 4: Creating an Admin Settings Page

We’ll build:

• Menu item in WordPress admin sidebar
• Settings page with HTML form
• Multiple input fields (text, checkbox, select)
• Save button that stores settings
• Load saved settings on page refresh
• Form validation and sanitization

All using simple HTML and PHP – no frameworks needed!

---

Congratulations on completing Episode 3! Your plugin now has intelligent theme compatibility checking. See you in Episode 4 where we’ll add a settings page!

---

Series: Building Versana Companion Plugin

Episode: 3 of ongoing series (Theme Compatibility Check)