Offline Mode

Taking Your Site Offline During Maintenance or Updates

This guide explains how to enable Offline Mode to display a clean maintenance page to visitors while you perform updates or maintenance on your WordPress site.

Note: Offline Mode support was added in version 0.11.7

What Is Offline Mode?

Offline Mode displays a professional maintenance page to all visitors while preventing access to your site. When enabled, visitors see:

• A clean offline page explaining maintenance is in progress
• Auto-refresh every 30 seconds to check if the site is back
• Proper 503 Service Unavailable status for search engines

This is different from Maintenance Mode, which uses .maintenance files and can affect specific tenants. Offline Mode is simpler - just add one constant to take the entire site offline.

When to Use Offline Mode

Use Offline Mode when:

• Deploying updates: Taking the site offline during code deployments
• Running migrations: Performing database updates that require downtime
• Emergency maintenance: Quick way to disable site access for critical fixes
• Scheduled maintenance: Planned maintenance windows

Use Maintenance Mode instead for routine maintenance or when you need tenant-specific control.

Required Configuration

Enable the Offline Constant

Add this constant at the top of your wp-config.php file (your main bootstrap file):

/**
 * Takes the entire site offline and displays a maintenance page.
 * Visitors will see a clean offline page with auto-refresh.
 * Remove or set to false to bring the site back online.
 */
define('OFFLINE_MODE', true);

That's it. The Framework detects this constant early and displays the offline page immediately.

What Happens When Enabled

Loaded:

• Clean offline maintenance page
• 503 Service Unavailable HTTP status
• Retry-After header (30 minutes by default)
• Auto-refresh functionality

Bypassed:

• WordPress initialization
• All site functionality
• Admin access (everyone sees the offline page)

The Offline Page Features

The offline page includes:

• Clean design matching Framework error pages
• Auto-refresh every 30 seconds
• "Refresh Page" and "Go Back" buttons
• Dark mode support
• Mobile responsive
• Search engine friendly (503 status)

Disabling Offline Mode

To bring your site back online:

Option 1: Comment out the constant

// define('OFFLINE_MODE', true);

Option 2: Set to false

define('OFFLINE_MODE', false);

Option 3: Remove the line entirely

The site will be immediately accessible once the constant is removed or set to false.

Automatic Detection

The Framework automatically:

• Detects the OFFLINE_MODE constant early in bootstrap
• Displays the offline page before any resource-intensive operations
• Sends proper HTTP headers and status codes
• No additional configuration needed

Verification

To verify offline mode is working:

1. Add define('OFFLINE_MODE', true); to your wp-config.php bootstrap file
2. Visit your site - you should see the offline page
3. Check that auto-refresh is working (watch the browser reload after 30 seconds)
4. Disable offline mode and verify the site loads normally

Check the HTTP status using browser developer tools or:

curl -I https://your-site.com
# Should show: HTTP/1.1 503 Service Unavailable

Troubleshooting

Common issues:

• Site still loads normally: Ensure constant is defined before Framework initialization
• Constant not taking effect: Check that it's boolean true, not string "true"
• Page doesn't auto-refresh: Clear browser cache and verify JavaScript is enabled
• Error instead of offline page: Ensure vendor/ directory exists (run composer install)

Recovery

If you need to access your site while offline mode is enabled:

1. Edit wp-config.php (the bootstrap file) via FTP or file manager
2. Comment out or remove define('OFFLINE_MODE', true);
3. Save the file
4. Site is immediately accessible again

Remember: This disables the entire site for everyone. Use it for deployments and critical maintenance, not routine updates.