Developer Guide: Backup Copilot Pro Hooks & Filters Reference

Backup Copilot Pro provides dozens of WordPress hooks and filters enabling developers to customize backup behavior, add integrations, and extend functionality without modifying core code. This comprehensive developer reference documents all available hooks with practical examples for common customizations from Slack notifications to custom retention policies.

Plugin Architecture Overview

Backup Copilot Pro follows WordPress plugin development standards with clearly defined extension points:

Action Hooks: Fire at specific points in backup workflow allowing custom code execution (notifications, logging, external integrations).

Filter Hooks: Modify data or behavior before processing (exclude files, customize metadata, adjust settings).

API Functions: Helper functions for accessing plugin functionality programmatically.

All hooks follow bkpc_* naming convention for easy identification and avoiding conflicts.

Action Hooks Reference

bkpc_before_backup_create

Fires immediately before backup creation starts.

Parameters: – $backup_type (string): Type of backup (“full”, “database”, “files”) – $options (array): Backup options and settings

Example – Log Backup Start:

add_action('bkpc_before_backup_create', 'log_backup_start', 10, 2);

function log_backup_start($backup_type, $options) {
    error_log(sprintf(
        '[Backup] Starting %s backup at %s',
        $backup_type,
        current_time('mysql')
    ));

    // Notify monitoring system
    wp_remote_post('https://monitoring.example.com/backup-started', [
        'body' => [
            'site' => get_site_url(),
            'type' => $backup_type,
            'timestamp' => time()
        ]
    ]);
}

bkpc_after_backup_create

Fires after backup creation completes successfully.

Parameters: – $backup_uuid (string): Unique backup identifier – $backup_data (array): Backup details (size, path, duration, etc.)

Example – Slack Notification:

add_action('bkpc_after_backup_create', 'notify_slack_backup_complete', 10, 2);

function notify_slack_backup_complete($backup_uuid, $backup_data) {
    $webhook_url = 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL';

    $message = sprintf(
        ':white_check_mark: Backup completed for %s\n' .
        'Type: %s | Size: %s | Duration: %s seconds',
        get_bloginfo('name'),
        $backup_data['type'],
        size_format($backup_data['size']),
        $backup_data['duration']
    );

    wp_remote_post($webhook_url, [
        'body' => json_encode(['text' => $message]),
        'headers' => ['Content-Type' => 'application/json']
    ]);
}

bkpc_backup_failed

Fires when backup fails for any reason.

Parameters: – $backup_uuid (string): Backup identifier – $error_message (string): Error description – $error_data (array): Additional error context

Example – Critical Error Alert:

add_action('bkpc_backup_failed', 'alert_backup_failure', 10, 3);

function alert_backup_failure($backup_uuid, $error_message, $error_data) {
    // Send critical alert to monitoring system
    wp_remote_post('https://monitoring.example.com/alert', [
        'body' => json_encode([
            'severity' => 'critical',
            'service' => 'wordpress_backup',
            'message' => $error_message,
            'site' => get_site_url(),
            'backup_id' => $backup_uuid,
            'context' => $error_data
        ]),
        'headers' => ['Content-Type' => 'application/json']
    ]);

    // Email site administrator
    wp_mail(
        get_option('admin_email'),
        '[CRITICAL] Backup Failed: ' . get_bloginfo('name'),
        sprintf(
            "Backup %s failed with error:\n\n%s\n\nTime: %s",
            $backup_uuid,
            $error_message,
            current_time('mysql')
        )
    );
}

bkpc_before_restore

Fires before restore operation begins.

Parameters: – $backup_uuid (string): Backup being restored – $restore_options (array): Restore settings (what to restore, overwrite options)

Example – Pre-Restore Backup:

add_action('bkpc_before_restore', 'create_pre_restore_backup', 10, 2);

function create_pre_restore_backup($backup_uuid, $restore_options) {
    // Create safety backup before restore
    if (function_exists('bkpc_create_backup')) {
        $safety_backup = bkpc_create_backup([
            'type' => 'full',
            'metadata' => [
                'purpose' => 'pre_restore_safety',
                'restoring_backup' => $backup_uuid
            ]
        ]);

        error_log('[Backup] Created pre-restore safety backup: ' . $safety_backup['uuid']);
    }
}

bkpc_after_restore

Fires after restore operation completes.

Parameters: – $backup_uuid (string): Restored backup ID – $restore_summary (array): What was restored and results

Example – Clear Caches Post-Restore:

add_action('bkpc_after_restore', 'clear_caches_after_restore', 10, 2);

function clear_caches_after_restore($backup_uuid, $restore_summary) {
    // Clear WordPress object cache
    wp_cache_flush();

    // Clear WP Rocket cache if active
    if (function_exists('rocket_clean_domain')) {
        rocket_clean_domain();
    }

    // Clear W3 Total Cache if active
    if (function_exists('w3tc_flush_all')) {
        w3tc_flush_all();
    }

    // Clear Cloudflare cache if configured
    $cf_zone_id = get_option('cloudflare_zone_id');
    $cf_api_key = get_option('cloudflare_api_key');

    if ($cf_zone_id && $cf_api_key) {
        wp_remote_post("https://api.cloudflare.com/client/v4/zones/{$cf_zone_id}/purge_cache", [
            'headers' => [
                'Authorization' => 'Bearer ' . $cf_api_key,
                'Content-Type' => 'application/json'
            ],
            'body' => json_encode(['purge_everything' => true])
        ]);
    }
}

bkpc_before_cloud_upload

Fires before backup uploads to cloud storage.

Parameters: – $backup_uuid (string): Backup being uploaded – $provider (string): Cloud provider ID – $local_path (string): Local backup file path

Example – Virus Scan Before Upload:

add_action('bkpc_before_cloud_upload', 'scan_backup_before_upload', 10, 3);

function scan_backup_before_upload($backup_uuid, $provider, $local_path) {
    // Scan with ClamAV before uploading
    $output = [];
    $return_var = 0;

    exec("clamscan --no-summary {$local_path}", $output, $return_var);

    if ($return_var !== 0) {
        // Virus detected - abort upload
        error_log('[Security] Virus detected in backup ' . $backup_uuid);
        throw new Exception('Backup failed virus scan');
    }
}

bkpc_after_cloud_upload

Fires after successful cloud upload.

Parameters: – $backup_uuid (string): Uploaded backup ID – $provider (string): Cloud provider – $remote_path (string): Cloud storage path – $upload_duration (int): Upload time in seconds

Example – Update External Database:

add_action('bkpc_after_cloud_upload', 'log_upload_to_external_db', 10, 4);

function log_upload_to_external_db($backup_uuid, $provider, $remote_path, $upload_duration) {
    global $wpdb;

    // Log to external monitoring database
    $wpdb->insert('backup_audit_log', [
        'site_id' => get_current_blog_id(),
        'site_url' => get_site_url(),
        'backup_id' => $backup_uuid,
        'provider' => $provider,
        'remote_path' => $remote_path,
        'upload_duration' => $upload_duration,
        'timestamp' => current_time('mysql')
    ]);
}

Filter Hooks Reference

bkpc_backup_excluded_files

Filter files and directories excluded from backup.

Parameters: – $excluded (array): Default exclusions

Returns: Modified exclusion array

Example – Exclude Custom Directories:

add_filter('bkpc_backup_excluded_files', 'exclude_custom_directories');

function exclude_custom_directories($excluded) {
    // Add custom exclusions
    $custom_exclusions = [
        '/wp-content/cache',
        '/wp-content/temp',
        '/wp-content/uploads/backups',
        '/wp-content/ai-training-data',  // Large AI model files
        '/node_modules',  // Development dependencies
        '/.git'  // Version control
    ];

    return array_merge($excluded, $custom_exclusions);
}

bkpc_backup_excluded_tables

Filter database tables excluded from backup.

Parameters: – $excluded_tables (array): Default excluded tables – $backup_type (string): Backup type

Returns: Modified table exclusion array

Example – Exclude Temporary Tables:

add_filter('bkpc_backup_excluded_tables', 'exclude_temp_tables', 10, 2);

function exclude_temp_tables($excluded_tables, $backup_type) {
    global $wpdb;

    // Exclude analytics tables (can be regenerated)
    $analytics_tables = [
        $wpdb->prefix . 'analytics_cache',
        $wpdb->prefix . 'statistics_temp',
        $wpdb->prefix . 'search_log'
    ];

    return array_merge($excluded_tables, $analytics_tables);
}

bkpc_backup_metadata

Filter backup metadata before save.

Parameters: – $metadata (array): Default metadata

Returns: Modified metadata array

Example – Add Custom Metadata:

add_filter('bkpc_backup_metadata', 'add_custom_backup_metadata');

function add_custom_backup_metadata($metadata) {
    // Add environment information
    $metadata['environment'] = wp_get_environment_type();  // production, staging, development

    // Add theme/plugin versions
    $metadata['active_theme'] = wp_get_theme()->get('Name') . ' ' . wp_get_theme()->get('Version');

    $active_plugins = [];
    foreach (get_option('active_plugins') as $plugin) {
        $plugin_data = get_plugin_data(WP_PLUGIN_DIR . '/' . $plugin);
        $active_plugins[] = $plugin_data['Name'] . ' ' . $plugin_data['Version'];
    }
    $metadata['active_plugins'] = $active_plugins;

    // Add WooCommerce order count if active
    if (class_exists('WooCommerce')) {
        $order_count = wp_count_posts('shop_order');
        $metadata['woocommerce_orders'] = $order_count->publish;
    }

    return $metadata;
}

bkpc_schedule_options

Filter schedule configuration before save.

Parameters: – $options (array): Schedule settings – $schedule_id (int): Schedule ID

Returns: Modified options array

Example – Enforce Backup Policies:

add_filter('bkpc_schedule_options', 'enforce_backup_policies', 10, 2);

function enforce_backup_policies($options, $schedule_id) {
    // Enforce minimum retention for production
    if (wp_get_environment_type() === 'production') {
        if ($options['retention_days'] < 30) {
            $options['retention_days'] = 30;
            error_log('[Backup] Enforced minimum 30-day retention for production');
        }

        // Require cloud upload for production
        $options['cloud_upload'] = true;
    }

    // Limit backup frequency to prevent server overload
    if ($options['frequency'] === 'hourly' && $options['backup_type'] === 'full') {
        $options['frequency'] = 'every_6_hours';
        error_log('[Backup] Reduced full backup frequency to prevent overload');
    }

    return $options;
}

bkpc_notification_email_content

Customize notification email content.

Parameters: – $content (array): Email content (subject, message, headers) – $backup_data (array): Backup details

Returns: Modified email content

Example – Customized Notification:

add_filter('bkpc_notification_email_content', 'customize_backup_email', 10, 2);

function customize_backup_email($content, $backup_data) {
    $content['subject'] = sprintf(
        '[%s] %s Backup %s',
        get_bloginfo('name'),
        ucfirst($backup_data['type']),
        $backup_data['status'] === 'completed' ? 'Completed' : 'Failed'
    );

    $content['message'] = sprintf(
        "Backup Report for %s\n" .
        "================================\n\n" .
        "Status: %s\n" .
        "Type: %s\n" .
        "Size: %s\n" .
        "Duration: %d seconds\n" .
        "Cloud Upload: %s\n" .
        "Timestamp: %s\n\n" .
        "View backup details: %s\n",
        get_bloginfo('name'),
        strtoupper($backup_data['status']),
        $backup_data['type'],
        size_format($backup_data['size']),
        $backup_data['duration'],
        $backup_data['cloud_uploaded'] ? 'Yes' : 'No',
        $backup_data['completed_at'],
        admin_url('admin.php?page=backup-copilot-pro&backup=' . $backup_data['uuid'])
    );

    // Add HTML version
    $content['headers'][] = 'Content-Type: text/html';

    return $content;
}

bkpc_cloud_upload_chunk_size

Customize upload chunk size for different providers.

Parameters: – $chunk_size (int): Default chunk size in bytes – $provider (string): Cloud provider ID

Returns: Modified chunk size

Example – Optimize Chunk Sizes:

add_filter('bkpc_cloud_upload_chunk_size', 'optimize_chunk_size', 10, 2);

function optimize_chunk_size($chunk_size, $provider) {
    // Different providers have different optimal chunk sizes
    $optimal_sizes = [
        'dropbox' => 10 * 1024 * 1024,      // 10MB for Dropbox
        'google_drive' => 5 * 1024 * 1024,   // 5MB for Google Drive
        'amazon_s3' => 15 * 1024 * 1024,     // 15MB for S3
        'backblaze' => 100 * 1024 * 1024     // 100MB for Backblaze B2
    ];

    return isset($optimal_sizes[$provider]) ? $optimal_sizes[$provider] : $chunk_size;
}

Advanced Integration Examples

Custom Retention Logic

Implement sophisticated retention policies:

add_filter('bkpc_retention_policy', 'custom_retention_logic', 10, 2);

function custom_retention_logic($should_delete, $backup_data) {
    // Keep all backups from the first of each month indefinitely
    $backup_date = new DateTime($backup_data['created_at']);
    if ($backup_date->format('d') === '01') {
        return false;  // Don't delete monthly backups
    }

    // Keep backups tagged as "before_major_update" for 1 year
    if (isset($backup_data['metadata']['tag']) &&
        $backup_data['metadata']['tag'] === 'before_major_update') {
        $age_days = (time() - strtotime($backup_data['created_at'])) / DAY_IN_SECONDS;
        return $age_days > 365;  // Delete after 1 year
    }

    // Default retention logic
    return $should_delete;
}

Database Query Optimization

Optimize database export queries:

add_filter('bkpc_database_export_query', 'optimize_export_query', 10, 2);

function optimize_export_query($query, $table) {
    // Skip certain columns from large tables
    $optimizations = [
        'wp_posts' => 'SELECT ID, post_author, post_date, post_content, post_title, post_status FROM',
        'wp_comments' => 'SELECT * FROM'  // Exclude spam comments
    ];

    foreach ($optimizations as $table_name => $select) {
        if (strpos($table, $table_name) !== false) {
            // Modify query for this table
            if ($table_name === 'wp_comments') {
                $query .= " WHERE comment_approved != 'spam'";
            }
        }
    }

    return $query;
}

Third-Party Service Integration

Integrate with external backup verification service:

add_action('bkpc_after_cloud_upload', 'verify_backup_externally', 10, 4);

function verify_backup_externally($backup_uuid, $provider, $remote_path, $duration) {
    // Send to external backup verification service
    $verification_service = 'https://backup-verify.example.com/api/verify';

    $backup_info = bkpc_get_backup($backup_uuid);

    wp_remote_post($verification_service, [
        'body' => json_encode([
            'site_id' => get_option('site_verification_id'),
            'backup_id' => $backup_uuid,
            'provider' => $provider,
            'remote_path' => $remote_path,
            'size' => $backup_info['size'],
            'checksum' => $backup_info['checksum'],
            'timestamp' => time()
        ]),
        'headers' => [
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . get_option('verification_api_key')
        ]
    ]);
}

Security Considerations

Validate All Inputs: When using filters that accept user input, always validate and sanitize.

Capability Checks: Ensure custom code respects WordPress capabilities:

add_action('bkpc_before_backup_create', 'log_backup_initiator', 10, 2);

function log_backup_initiator($backup_type, $options) {
    if (!current_user_can('manage_options')) {
        return;  // Only log for administrators
    }

    // Log who initiated backup
}

Prevent Information Disclosure: Don’t expose sensitive information in logs or notifications.

Rate Limiting: External API calls should implement retry limits and exponential backoff.

Performance Impact

Minimize Hook Execution Time: Keep hook callbacks fast. Defer long operations:

add_action('bkpc_after_backup_create', 'defer_slow_operation', 10, 2);

function defer_slow_operation($backup_uuid, $backup_data) {
    // Schedule slow operation for later rather than blocking
    wp_schedule_single_event(time() + 60, 'process_backup_analytics', [$backup_uuid]);
}

Cache When Possible: Don’t repeat expensive operations unnecessarily.

Async for External Calls: Use blocking => false for non-critical external requests:

wp_remote_post($url, [
    'blocking' => false,  // Don't wait for response
    'timeout' => 5,
    'body' => $data
]);

Debugging Custom Integrations

Enable WordPress debugging and use error logging:

add_action('bkpc_before_backup_create', 'debug_backup_hooks', 10, 2);

function debug_backup_hooks($backup_type, $options) {
    if (defined('WP_DEBUG') && WP_DEBUG) {
        error_log('=== Backup Hook Debug ===');
        error_log('Type: ' . $backup_type);
        error_log('Options: ' . print_r($options, true));
        error_log('Current user: ' . wp_get_current_user()->user_login);
        error_log('Memory usage: ' . size_format(memory_get_usage(true)));
        error_log('========================');
    }
}

Best Practices

Use Priority Wisely: Default priority is 10. Lower numbers run first, higher run later. Critical operations should run early (priority 5), non-critical later (priority 20).

Check Function Existence: Always verify functions exist before calling:

if (function_exists('bkpc_create_backup')) {
    // Safe to call
}

Document Custom Code: Comment your hooks explaining what they do and why.

Test Thoroughly: Test custom hooks with various backup types, sizes, and failure scenarios.

Plugin Compatibility: Check for conflicts with other backup or security plugins.

Conclusion

Backup Copilot Pro’s extensive hook and filter system provides complete customization without touching core code. From simple exclusions to complex integrations with external services, the architecture supports sophisticated workflows while maintaining compatibility and performance.

Action hooks enable event-driven integrations, filter hooks allow data manipulation, proper implementation ensures security and performance, and thorough testing prevents issues in production. Whether adding Slack notifications, implementing custom retention policies, or integrating with enterprise monitoring systems, these hooks provide the foundation for extending Backup Copilot Pro to meet any requirement.

External Links

Call to Action

Ready to extend Backup Copilot Pro? Get Pro and access our complete API documentation, developer support, and custom integration assistance. Build exactly what you need!