tigerstyle-heat/docs/BACKUP_MODULE_DOCUMENTATION.md

TigerStyle Heat - Enterprise Backup & Restore Module

Overview

The TigerStyle Heat Backup & Restore module is an enterprise-grade backup and restore system for WordPress that provides comprehensive site protection with advanced features including chunked processing, multiple compression formats, S3 storage integration, and sophisticated validation systems.

Features

Core Backup Features

• Complete WordPress Backup: Files + Database with selective inclusion options
• Chunked Processing: Handles large sites without memory/timeout issues
• Multiple Compression: ZIP, TAR.GZ, TAR.BZ2 with graceful fallback
• Progress Tracking: Real-time AJAX progress updates
• Backup Validation: Comprehensive integrity checking with checksums
• Backup Manifest: Detailed metadata for each backup

Storage Options

• Local Storage: WordPress uploads directory with organized structure
• S3 Compatible Storage: Full S3 integration with metadata and encryption
• S3-Compatible: Support for MinIO, DigitalOcean Spaces, etc.
• Storage Stats: Usage tracking and space monitoring

Restore Features

• Safe Restoration: Validation before restore with rollback backup creation
• Selective Restore: Choose files, database, or both
• Progress Tracking: Real-time restore progress monitoring
• URL Management: Automatic site URL handling during restore

Advanced Features

• WordPress Reset: Remove default content to prepare for restore
• Database Reset: Complete database wipe with multi-level confirmation
• Scheduled Backups: Automated backups with retention policies
• Email Notifications: Success/failure notifications
• Comprehensive Logging: Multi-level logging with export capabilities

Architecture

Core Classes

TigerStyleSEO_Backup_Restore

Main module coordinator that orchestrates all backup operations.

$backup_module = tigerstyle_heat()->get_module('backup_restore');

TigerStyleSEO_Backup_Engine

Core backup processing engine with chunked file handling.

Key Methods:

• create_backup($options) - Create new backup
• backup_database() - MySQL dump with table-level processing
• backup_files() - Recursive file backup with exclusions
• create_backup_manifest() - Generate backup metadata

TigerStyleSEO_Restore_Engine

Restoration engine with safety checks and validation.

Key Methods:

• restore_backup($options) - Restore from backup
• validate_backup_integrity() - Pre-restore validation
• create_rollback_backup() - Safety backup before restore

TigerStyleSEO_Storage_Manager

Multi-backend storage management.

Storage Backends:

• Local filesystem storage
• S3 Compatible Storage with encryption
• S3-compatible services

TigerStyleSEO_Compression_Manager

Multi-format compression with fallback.

Supported Formats:

• ZIP (preferred)
• TAR.GZ
• TAR.BZ2
• TAR (uncompressed fallback)

TigerStyleSEO_Backup_Logger

Enterprise logging system with multiple outputs.

Log Levels:

• Debug, Info, Warning, Error, Critical
• File-based logging with rotation
• Database storage for recent logs
• Email notifications for critical errors

TigerStyleSEO_Backup_Validator

Comprehensive backup validation system.

Validation Checks:

• File integrity and checksums
• Database structure validation
• Manifest verification
• Cross-platform compatibility

TigerStyleSEO_Backup_Scheduler

Automated backup scheduling with retention policies.

Features:

• Hourly, daily, weekly, monthly schedules
• System load checking
• Retention policies
• Failure tracking

Database Schema

Backup Metadata Table

CREATE TABLE wp_tigerstyle_backup_metadata (
    id int(11) NOT NULL AUTO_INCREMENT,
    backup_id varchar(255) NOT NULL,
    storage_type varchar(50) NOT NULL,
    file_path text,
    s3_bucket varchar(255),
    s3_key varchar(500),
    s3_url text,
    file_size bigint(20) NOT NULL DEFAULT 0,
    created_at datetime NOT NULL,
    metadata_json text,
    PRIMARY KEY (id),
    UNIQUE KEY backup_id (backup_id)
);

Backup Logs Table

CREATE TABLE wp_tigerstyle_backup_logs (
    id int(11) NOT NULL AUTO_INCREMENT,
    level varchar(20) NOT NULL,
    message text NOT NULL,
    context longtext,
    user_id int(11) DEFAULT 0,
    ip_address varchar(45),
    created_at datetime NOT NULL,
    PRIMARY KEY (id),
    KEY level (level),
    KEY created_at (created_at)
);

Configuration

Default Settings

$default_settings = array(
    'compression' => 'zip',
    'storage_location' => 'local',
    'schedule_enabled' => false,
    'schedule_frequency' => 'daily',
    'retention_days' => 30,
    'include_files' => true,
    'include_database' => true,
    'chunk_size' => 5, // MB
    's3_bucket' => '',
    's3_access_key' => '',
    's3_secret_key' => '',
    's3_region' => 'us-east-1',
    's3_endpoint' => '',
    'email_notifications' => false,
    'notification_email' => get_option('admin_email')
);

S3 Configuration

For AWS S3 or S3-compatible services:

$s3_settings = array(
    's3_bucket' => 'your-backup-bucket',
    's3_access_key' => 'AKIA...',
    's3_secret_key' => 'your-secret-key',
    's3_region' => 'us-east-1',
    's3_endpoint' => 'https://s3.amazonaws.com' // Optional for S3-compatible
);

API Usage

Creating a Backup

$backup_engine = new TigerStyleSEO_Backup_Engine();
$backup_id = $backup_engine->create_backup(array(
    'type' => 'full',
    'compression' => 'zip',
    'storage_location' => 'local',
    'include_files' => true,
    'include_database' => true,
    'description' => 'Manual backup before update'
));

Restoring from Backup

$restore_engine = new TigerStyleSEO_Restore_Engine();
$restore_id = $restore_engine->restore_backup(array(
    'backup_id' => $backup_id,
    'restore_files' => true,
    'restore_database' => true,
    'create_rollback' => true,
    'validate_before_restore' => true
));

Validating a Backup

$validator = new TigerStyleSEO_Backup_Validator();
$result = $validator->validate_backup($backup_id);

if ($result['valid']) {
    echo "Backup is valid";
} else {
    foreach ($result['errors'] as $error) {
        echo "Error: " . $error;
    }
}

AJAX Endpoints

Backup Operations

• tigerstyle_create_backup - Create new backup
• tigerstyle_restore_backup - Restore from backup
• tigerstyle_backup_progress - Get operation progress
• tigerstyle_validate_backup - Validate backup integrity

Management Operations

• tigerstyle_delete_backup - Delete backup
• tigerstyle_download_backup - Download backup file
• tigerstyle_upload_backup - Upload backup file

Advanced Operations

• tigerstyle_reset_wordpress - Reset WordPress content
• tigerstyle_reset_database - Complete database reset
• tigerstyle_test_s3_connection - Test S3 connectivity

Logging & Stats

• tigerstyle_get_backup_logs - Retrieve backup logs
• tigerstyle_backup_stats - Get backup statistics

Security Features

Access Control

• WordPress capability checks (manage_options)
• Nonce verification for all operations
• User ID tracking in logs

Confirmation Systems

• Text confirmation for destructive operations
• Random code generation for database reset
• Multi-level confirmations for critical actions

Data Protection

• Backup file encryption in S3
• Protected log directory with .htaccess
• Temporary file cleanup
• Secure file handling

Performance Optimizations

Memory Management

• Chunked file processing (configurable chunk size)
• Streaming operations for large files
• Memory limit increases where possible
• Garbage collection optimization

Timeout Handling

• Set unlimited execution time for operations
• Progress tracking for long operations
• Resumable operations where possible

System Resource Monitoring

• Load average checking before scheduled backups
• Disk space validation
• Concurrent operation prevention

Error Handling & Recovery

Backup Failures

• Automatic cleanup of partial backups
• Failure logging with context
• Graceful degradation (compression fallback)
• Retry mechanisms for network operations

Restore Failures

• Automatic rollback on restore failure
• Progress state preservation
• Detailed error reporting
• Recovery recommendations

Validation Failures

• Comprehensive integrity checking
• Detailed validation reports
• Granular error categorization
• Recovery suggestions

Monitoring & Logging

Log Levels

• Debug: Detailed operation information
• Info: General operation status
• Warning: Non-critical issues
• Error: Operation failures
• Critical: System-threatening issues

Log Storage

• File-based logs with rotation (10MB limit)
• Database storage for recent logs (1000 entries)
• WordPress debug.log integration
• Log export functionality

Notifications

• Email notifications for failures
• Configurable notification levels
• Rate limiting to prevent spam
• Template-based email formatting

Integration Points

WordPress Hooks

• tigerstyle_backup_restore_completed - After successful restore
• tigerstyle_backup_created - After backup creation
• tigerstyle_backup_scheduled - Scheduled backup trigger
• tigerstyle_backup_cleanup - Cleanup trigger

Filter Hooks

• tigerstyle_backup_paths - Modify backup file paths
• tigerstyle_backup_logging_enabled - Control logging
• tigerstyle_backup_exclude_patterns - File exclusion patterns

Admin Integration

• Tab in main TigerStyle Heat admin interface
• Progress indicators and real-time updates
• Comprehensive settings management
• Backup list and management interface

File Structure

includes/
├── modules/
│   └── class-backup-restore.php          # Main module class
└── backup/
    ├── class-backup-engine.php           # Core backup processing
    ├── class-restore-engine.php          # Restoration engine
    ├── class-storage-manager.php         # Multi-backend storage
    ├── class-backup-logger.php           # Comprehensive logging
    ├── class-backup-validator.php        # Integrity validation
    ├── class-backup-scheduler.php        # Automated scheduling
    ├── class-compression-manager.php     # Multi-format compression
    └── ajax-handlers.php                 # AJAX endpoints

admin/
└── pages/
    └── backup-restore.php                # Admin interface

Requirements

PHP Requirements

• PHP 7.4 or higher
• Memory: 256MB+ recommended
• Execution time: Unlimited for large backups

WordPress Requirements

• WordPress 5.0 or higher
• manage_options capability for users

System Requirements

• Available disk space (2x backup size recommended)
• ZIP extension (preferred) or TAR support
• cURL for S3 operations
• MySQL/MariaDB access for database operations

Optional Requirements

• AWS SDK for advanced S3 features
• ionCube for PHP acceleration
• WP-CLI for command-line operations

Best Practices

Backup Strategy

1. Regular Schedules: Set up automated daily/weekly backups
2. Before Updates: Always backup before major updates
3. Multiple Locations: Use both local and S3 storage
4. Retention Policies: Keep 30 days of backups minimum
5. Test Restores: Regularly test backup restoration

Security Practices

1. S3 Permissions: Use dedicated IAM user with minimal permissions
2. Backup Encryption: Enable S3 server-side encryption
3. Access Control: Limit backup access to administrators
4. Log Monitoring: Monitor backup logs for suspicious activity

Performance Optimization

1. Chunk Size: Adjust based on server resources (5MB default)
2. Exclusion Patterns: Exclude unnecessary files (cache, logs)
3. Compression: Use ZIP for best compatibility and speed
4. Scheduling: Run backups during low-traffic hours

Troubleshooting

Common Issues

Memory Exhaustion

• Reduce chunk size in settings
• Exclude large directories (uploads/cache)
• Increase PHP memory limit
• Use streaming operations

Timeout Issues

• Set unlimited execution time
• Use chunked processing
• Check server timeout settings
• Monitor progress tracking

S3 Connection Issues

• Verify credentials and permissions
• Check bucket region settings
• Test with S3 endpoint override
• Monitor network connectivity

Validation Failures

• Check file permissions
• Verify backup integrity
• Review compression settings
• Check available disk space

Debug Mode

Enable WordPress debug mode for detailed logging:

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

Changelog

Version 1.0.0

• Initial release with core backup/restore functionality
• S3 storage integration
• Comprehensive logging system
• Advanced validation and safety features
• Enterprise-grade admin interface
• Automated scheduling and retention policies

---

Support

For technical support, please review the logs first:

1. Check backup logs in the admin interface
2. Review WordPress debug logs
3. Verify system requirements
4. Test with minimal configuration

This module represents enterprise-grade backup functionality that can compete with premium backup plugins while being deeply integrated with the TigerStyle Heat ecosystem.