ScubaGPT Install Safety Features

Overview

ScubaGPT includes comprehensive safety mechanisms to prevent the plugin from crashing WordPress during installation, updates, or normal operation.

Safety Layers

1. Activation Safety

Pre-Activation Checks

• PHP Version: Requires PHP 8.0+
• WordPress Version: Requires WordPress 6.0+
• PHP Extensions: curl, json, mbstring, mysqli
• Memory Limit: Minimum 64MB
• File Permissions: Upload directory must be writable

Safe File Loading

• All includes wrapped in try-catch blocks
• Missing file detection and logging
• Graceful degradation for optional files
• Detailed error reporting for critical files

Database Creation Safety

• Permission checks before table creation
• Transaction support where available
• Table existence verification after creation
• Detailed error logging with database errors
• Automatic rollback on failure

Activation Error Handling

• Plugin auto-deactivates on fatal errors
• Detailed error messages with troubleshooting steps
• Error stored in options for admin review
• No partial activation – all-or-nothing approach

2. Update Safety

Version Detection

• Automatic version checking on admin init
• Comparison of installed vs. current version
• Triggered upgrade process when versions differ

Safe Upgrade Process

1. Start database transaction (if supported)
2. Create backup of critical options
3. Perform version-specific upgrades
4. Update database schema safely
5. Verify upgrade success
6. Commit transaction
7. Update version number
8. Clear caches

Rollback on Failure

• Automatic transaction rollback on error
• Options restored from backup
• Previous version number maintained
• Admin notice displayed with error details

Version-Specific Upgrades

• 1.1.0: Safety system implementation
• 1.2.0: AI Engine settings, External API settings, disambiguation cache clear

3. Database Migration Safety

Schema Updates

• Uses WordPress dbDelta() for safe schema changes
• Adds columns without removing existing data
• Verifies table existence before operations
• Never drops tables or columns automatically

Migration Strategy

• Check if tables exist
• Create if missing
• Update schema if exists (additive only)
• Verify critical tables after migration

4. Fatal Error Protection

Shutdown Handler

• Registered on plugin construction
• Detects fatal errors from plugin files
• Logs errors with full details
• Increments error counter

Auto-Disable Mechanism

• Tracks consecutive fatal errors
• Auto-disables after 3 fatal errors
• Prevents infinite error loops
• Sets emergency shutdown flag

Emergency Shutdown

• Plugin stops loading on emergency shutdown
• Admin notice displayed with recovery instructions
• Manual reactivation required after fixing issue
• Error count reset on successful activation

5. Safe Loader Class

Purpose

Prevents fatal errors from missing or corrupted files.

Features

• Validates file existence before requiring
• Wraps requires in try-catch blocks
• Tracks missing files and load errors
• Distinguishes critical vs. optional files
• Provides detailed error reporting

Usage

$files = [
    ['/path/to/file.php', 'Description', true],  // critical
    ['/path/to/optional.php', 'Optional', false], // optional
];

foreach ($files as $file) {
    list($path, $description, $critical) = $file;
    $loaded = ScubaGPT_Safe_Loader::require_file($path, $description);
    
    if (!$loaded && $critical) {
        // Handle critical file missing
    }
}

Error Recovery

Activation Errors

Symptoms:

• Plugin fails to activate
• Error message displayed
• Plugin automatically deactivated

Recovery Steps:

1. Check system requirements
2. Verify database permissions
3. Check error logs
4. Fix underlying issue
5. Try reactivation

Upgrade Errors

Symptoms:

• Admin notice about upgrade failure
• Plugin continues running on old version
• Settings restored from backup

Recovery Steps:

1. Review error message in admin notice
2. Check server error logs
3. Deactivate and reactivate plugin
4. Contact support if issue persists

Fatal Errors

Symptoms:

• Plugin auto-disabled after 3 errors
• Emergency shutdown notice
• Plugin stops loading

Recovery Steps:

1. Check error logs for fatal error details
2. Fix the underlying issue
3. Reset error count (optional):

   delete_option('scubagpt_error_count');
   delete_option('scubagpt_emergency_shutdown');

1. Reactivate plugin

Admin Notices

Activation Error Notice

• Displayed when activation fails
• Shows specific error message
• Provides troubleshooting steps
• Link to return to plugins page

Upgrade Error Notice

• Displayed when upgrade fails
• Shows version information
• Confirms settings restored
• Dismissible with AJAX

Emergency Shutdown Notice

• Displayed when plugin auto-disabled
• Shows error count and reason
• Provides recovery instructions
• Requires manual intervention

Database Safety

Table Creation

• Strict dbDelta() formatting requirements
• Two spaces after PRIMARY KEY
• KEY instead of INDEX
• Each field on own line
• No IF NOT EXISTS (handled by dbDelta)

Schema Updates

• Additive only (no column removal)
• Preserves existing data
• Backward compatible
• Version tracked in options

Transaction Support

$wpdb->query('START TRANSACTION');
try {
    // Perform operations
    $wpdb->query('COMMIT');
} catch (Exception $e) {
    $wpdb->query('ROLLBACK');
}

Options Backup

Backed Up Options

• scubagpt_claude_settings
• scubagpt_pinecone_settings
• scubagpt_tavily_settings
• scubagpt_general_settings
• scubagpt_system_prompt
• scubagpt_ai_engine_settings
• scubagpt_external_api_settings

Backup Storage

• Stored in scubagpt_options_backup
• Timestamp in scubagpt_backup_time
• Created before each upgrade
• Restored on upgrade failure

Cache Management

Cached Data

• Disambiguation files (24 hours)
• External API responses (30 minutes)
• Various transients

Cache Clearing

• Automatic on plugin update
• Automatic on version upgrade
• Manual via clear_all_caches() method

Cache Keys

• scubagpt_disambiguations
• _transient_scubagpt_*
• _transient_timeout_scubagpt_*

Logging

Error Logging

All errors logged to PHP error log with prefix ScubaGPT::

ScubaGPT: Activation started
ScubaGPT: Upgrading from 1.1.0 to 1.2.0
ScubaGPT: Fatal Error: ...
ScubaGPT: Emergency shutdown - plugin auto-disabled

Logged Events

• Activation attempts and results
• Upgrade attempts and results
• Fatal errors with file/line
• Emergency shutdowns
• Database errors
• Missing files

Best Practices

For Administrators

1. Before Updating:

• Backup your database
• Backup WordPress files
• Test on staging site first

1. After Updating:

• Check for admin notices
• Review error logs
• Test chatbot functionality
• Verify settings preserved

1. If Issues Occur:

• Don’t panic – settings are backed up
• Read error messages carefully
• Check server error logs
• Contact support with error details

For Developers

1. Adding New Features:

• Mark optional files as non-critical
• Wrap risky operations in try-catch
• Add version-specific upgrade logic
• Test upgrade path thoroughly

1. Database Changes:

• Only additive schema changes
• Use dbDelta() for safety
• Verify changes after application
• Document in version upgrades

1. Testing:

• Test fresh installation
• Test upgrade from previous version
• Test with missing files
• Test with database errors
• Test with insufficient permissions

Version Tracking

Options Used

• scubagpt_version – Current plugin version
• scubagpt_db_version – Database schema version
• scubagpt_last_upgrade – Timestamp of last upgrade
• scubagpt_activation_time – Timestamp of activation

Status Options

• scubagpt_activation_status – success/failed
• scubagpt_error_count – Fatal error counter
• scubagpt_emergency_shutdown – Emergency shutdown flag

Support Information

Error Data Collection

When contacting support, provide:

1. Error message from admin notice
2. Server error log entries (with ScubaGPT prefix)
3. WordPress version
4. PHP version
5. Active plugins list
6. Database error (if shown)

Debug Mode

Enable WordPress debug mode for detailed errors:

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

Summary

ScubaGPT’s safety features ensure:

• ✅ Plugin never crashes WordPress
• ✅ Failed activations are clean and reversible
• ✅ Failed upgrades restore previous settings
• ✅ Fatal errors trigger auto-disable
• ✅ Database operations are transactional
• ✅ All errors are logged and reported
• ✅ Admin notices guide recovery
• ✅ Settings are backed up before changes

The plugin is designed to fail gracefully and provide clear recovery paths for any issues that occur.