Step-by-Step Guide to building a custom automated database backup engine block for Gutenberg using React components
Setting Up the WordPress Plugin and React Environment
Before diving into the custom backup engine, we need a foundational WordPress plugin structure and a React development environment. This involves creating a basic plugin file and configuring a modern JavaScript build process, typically using `@wordpress/scripts` for seamless integration with the WordPress ecosystem.
First, create a new directory for your plugin within the wp-content/plugins/ directory of your WordPress installation. Let’s name it custom-db-backup.
Inside this directory, create the main plugin file, custom-db-backup.php.
[php]
<?php
/**
* Plugin Name: Custom DB Backup Engine
* Description: A custom Gutenberg block for automated database backups.
* Version: 1.0.0
* Author: Your Name
* License: GPL-2.0+
* License URI: http://www.gnu.org/licenses/gpl-2.0.txt
* Text Domain: custom-db-backup
*/
// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Enqueue Gutenberg block assets.
*/
function custom_db_backup_enqueue_block_assets() {
// Enqueue the editor script.
wp_enqueue_script(
'custom-db-backup-editor-script',
plugins_url( 'build/index.js', __FILE__ ),
array( 'wp-blocks', 'wp-wp-data', 'wp-edit-post' ),
filemtime( plugin_dir_path( __FILE__ ) . 'build/index.js' )
);
// Enqueue the editor stylesheet.
wp_enqueue_style(
'custom-db-backup-editor-style',
plugins_url( 'build/index.css', __FILE__ ),
array( 'wp-edit-blocks' ),
filemtime( plugin_dir_path( __FILE__ ) . 'build/index.css' )
);
// Enqueue the frontend stylesheet.
wp_enqueue_style(
'custom-db-backup-frontend-style',
plugins_url( 'build/style-index.css', __FILE__ ),
array(),
filemtime( plugin_dir_path( __FILE__ ) . 'build/style-index.css' )
);
}
add_action( 'enqueue_block_editor_assets', 'custom_db_backup_enqueue_block_assets' );
/**
* Register the custom block.
*/
function custom_db_backup_register_block() {
register_block_type( __DIR__ );
}
add_action( 'init', 'custom_db_backup_register_block' );
[/php]
Next, initialize a Node.js project and install the necessary development dependencies. Navigate to your plugin directory in the terminal and run:
[shell] npm init -y npm install @wordpress/scripts --save-dev [/shell]
Add a build script to your package.json file to compile your React components and JavaScript into the build directory.
[json]
{
"name": "custom-db-backup",
"version": "1.0.0",
"description": "A custom Gutenberg block for automated database backups.",
"main": "build/index.js",
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start"
},
"keywords": ["wordpress", "gutenberg", "block", "backup"],
"author": "Your Name",
"license": "GPL-2.0-or-later",
"devDependencies": {
"@wordpress/scripts": "^26.10.0"
}
}
[/json]
Create a src directory within your plugin folder. Inside src, create index.js and block.json.
Defining the Gutenberg Block with block.json
The block.json file serves as the manifest for your Gutenberg block, defining its metadata, attributes, and script dependencies. This is crucial for WordPress to recognize and load your block correctly.
[json]
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "custom-db-backup/engine",
"version": "1.0.0",
"title": "Custom DB Backup Engine",
"category": "widgets",
"icon": "database",
"description": "Manages automated database backups.",
"attributes": {
"backupFrequency": {
"type": "string",
"default": "daily"
},
"backupTime": {
"type": "string",
"default": "02:00"
},
"backupRetention": {
"type": "number",
"default": 7
},
"enableEmailNotifications": {
"type": "boolean",
"default": false
},
"emailAddress": {
"type": "string",
"default": ""
}
},
"editorScript": "file:./build/index.js",
"editorStyle": "file:./build/index.css",
"style": "file:./build/style-index.css",
"supports": {
"html": false
}
}
[/json]
In this block.json:
name: A unique identifier for the block (namespace/block-name).title: The human-readable name displayed in the block inserter.category: The category the block belongs to.icon: The icon displayed for the block.description: A brief explanation of the block’s purpose.attributes: Defines the data that the block will store. We’ve included settings for backup frequency, time, retention, and email notifications.editorScript,editorStyle,style: Point to the compiled JavaScript and CSS files.
Developing the React Components for the Block Editor
The core of our custom block lies in its React components, which will handle the user interface within the Gutenberg editor. We’ll use the @wordpress/components and @wordpress/i18n packages for UI elements and internationalization.
Create src/index.js to register the block and define its editor and save components.
[javascript]
import { registerBlockType } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';
import {
PanelBody,
SelectControl,
Text time,
ToggleControl,
TextControl,
Button,
} from '@wordpress/components';
import { InspectorControls, useBlockProps } from '@wordpress/block-editor';
import './style.scss'; // For frontend styles
import './editor.scss'; // For editor-specific styles
import metadata from './block.json';
const Edit = ( { attributes, setAttributes } ) => {
const blockProps = useBlockProps();
const {
backupFrequency,
backupTime,
backupRetention,
enableEmailNotifications,
emailAddress,
} = attributes;
const frequencyOptions = [
{ label: __( 'Daily', 'custom-db-backup' ), value: 'daily' },
{ label: __( 'Weekly', 'custom-db-backup' ), value: 'weekly' },
{ label: __( 'Monthly', 'custom-db-backup' ), value: 'monthly' },
];
const handleSaveSettings = () => {
// This is where we'd typically send settings to the backend via AJAX
// For now, we'll just log it.
console.log( 'Saving backup settings:', {
backupFrequency,
backupTime,
backupRetention,
enableEmailNotifications,
emailAddress,
} );
alert( __( 'Backup settings saved (check console for details).', 'custom-db-backup' ) );
};
return (
<div { ...blockProps }>
<InspectorControls>
<PanelBody title={ __( 'Backup Settings', 'custom-db-backup' ) } initialOpen={ true }>
<SelectControl
label={ __( 'Backup Frequency', 'custom-db-backup' ) }
value={ backupFrequency }
options={ frequencyOptions }
onChange={ ( newFrequency ) => setAttributes( { backupFrequency: newFrequency } ) }
/>
<Text time
label={ __( 'Backup Time', 'custom-db-backup' ) }
value={ backupTime }
onChange={ ( newTime ) => setAttributes( { backupTime: newTime } ) }
help={ __( 'Format: HH:MM (24-hour clock)', 'custom-db-backup' ) }
/>
<TextControl
label={ __( 'Backup Retention (Days)', 'custom-db-backup' ) }
type="number"
value={ backupRetention }
onChange={ ( newRetention ) => setAttributes( { backupRetention: parseInt( newRetention, 10 ) } ) }
min="1"
/>
<ToggleControl
label={ __( 'Enable Email Notifications', 'custom-db-backup' ) }
checked={ enableEmailNotifications }
onChange={ ( isEnabled ) => setAttributes( { enableEmailNotifications: isEnabled } ) }
/>
{ enableEmailNotifications && (
<TextControl
label={ __( 'Email Address', 'custom-db-backup' ) }
value={ emailAddress }
onChange={ ( newEmail ) => setAttributes( { emailAddress: newEmail } ) }
type="email"
/>
) }
<Button
variant="primary"
onClick={ handleSaveSettings }
style={ { marginTop: '20px' } }
>
{ __( 'Save Backup Settings', 'custom-db-backup' ) }
</Button>
</PanelBody>
</InspectorControls>
<div className="custom-db-backup-editor-content">
<h3>{ __( 'Database Backup Engine', 'custom-db-backup' ) }</h3>
<p>{ __( 'Configure your backup settings in the sidebar.', 'custom-db-backup' ) }</p>
</div>
</div>
);
};
const Save = ( { attributes } ) => {
const blockProps = useBlockProps.save();
// The save function should return minimal markup, as settings are handled server-side.
// We might display a confirmation or status here if needed.
return (
<div { ...blockProps }>
<p>{ __( 'Database backup configured.', 'custom-db-backup' ) }</p>
<p>{ __( 'Frequency:', 'custom-db-backup' ) } { attributes.backupFrequency }</p>
</div>
);
};
registerBlockType( metadata.name, {
edit: Edit,
save: Save,
} );
[/javascript]
In this index.js:
- We import necessary components from
@wordpress/blocks,@wordpress/i18n,@wordpress/components, and@wordpress/block-editor. - The
Editcomponent renders the block’s interface in the editor. It usesInspectorControlsto place settings within the block sidebar. PanelBody,SelectControl,Text time,ToggleControl, andTextControlare used to create input fields for backup settings.- The
setAttributesfunction is used to update the block’s attributes whenever a setting changes. - A placeholder
handleSaveSettingsfunction demonstrates where you would implement AJAX calls to save these settings to the WordPress database. - The
Savecomponent defines the static HTML output for the frontend. For a backup engine, this might be minimal, as the actual backup logic is server-side. - Finally,
registerBlockTyperegisters our block using the metadata fromblock.jsonand assigns ourEditandSavecomponents.
Styling the Block
Create src/editor.scss for styles that only apply within the block editor and src/style.scss for styles that apply both in the editor and on the frontend.
[css]
/* src/editor.scss */
.custom-db-backup-editor-content {
border: 1px dashed #ccc;
padding: 20px;
text-align: center;
background-color: #f9f9f9;
}
[/css]
[css]
/* src/style.scss */
.wp-block-custom-db-backup-engine {
border: 1px solid #eee;
padding: 15px;
background-color: #fff;
margin-bottom: 20px;
}
.wp-block-custom-db-backup-engine p {
margin-bottom: 5px;
}
[/css]
Building the Block Assets
With the React components and styles in place, run the build script from your plugin’s root directory:
[shell] npm run build [/shell]
This command will compile your src/index.js and src/style.scss into build/index.js, build/index.css, and build/style-index.css, respectively. These are the files enqueued in your custom-db-backup.php.
Implementing the Backend Logic for Backups
The React components handle the UI and saving settings. The actual backup mechanism needs to be implemented on the server-side. This involves creating a WordPress cron job (WP-Cron) to trigger backups and a function to perform the database export.
First, let’s add a function to save the block’s attributes to the WordPress options API. We’ll hook into the rest_api_init action to create a custom REST API endpoint.
[php]
/**
* Register REST API endpoint for saving backup settings.
*/
function custom_db_backup_register_rest_route() {
register_rest_route( 'custom-db-backup/v1', '/settings', array(
'methods' => 'POST',
'callback' => 'custom_db_backup_save_settings_callback',
'permission_callback' => function () {
// Ensure only users with 'manage_options' capability can access.
return current_user_can( 'manage_options' );
},
'args' => array(
'backupFrequency' => array(
'required' => true,
'type' => 'string',
'enum' => array( 'daily', 'weekly', 'monthly' ),
'sanitize_callback' => 'sanitize_text_field',
),
'backupTime' => array(
'required' => true,
'type' => 'string',
'format' => 'time', // Basic format validation
'sanitize_callback' => 'sanitize_text_field',
),
'backupRetention' => array(
'required' => true,
'type' => 'integer',
'minimum' => 1,
'sanitize_callback' => 'absint',
),
'enableEmailNotifications' => array(
'required' => true,
'type' => 'boolean',
'sanitize_callback' => 'rest_sanitize_boolean',
),
'emailAddress' => array(
'required' => false, // Only required if enableEmailNotifications is true
'type' => 'string',
'format' => 'email',
'sanitize_callback' => 'sanitize_email',
),
),
) );
}
add_action( 'rest_api_init', 'custom_db_backup_register_rest_route' );
/**
* Callback function to save backup settings.
*/
function custom_db_backup_save_settings_callback( WP_REST_Request $request ) {
$settings = array(
'backup_frequency' => $request->get_param( 'backupFrequency' ),
'backup_time' => $request->get_param( 'backupTime' ),
'backup_retention' => $request->get_param( 'backupRetention' ),
'enable_email_notifications' => $request->get_param( 'enableEmailNotifications' ),
'email_address' => $request->get_param( 'emailAddress' ),
);
// Validate email address if notifications are enabled
if ( $settings['enable_email_notifications'] && ! is_email( $settings['email_address'] ) ) {
return new WP_Error( 'invalid_email', __( 'Invalid email address provided.', 'custom-db-backup' ), array( 'status' => 400 ) );
}
update_option( 'custom_db_backup_settings', $settings );
// Schedule/reschedule the backup cron job based on new settings
custom_db_backup_schedule_cron( $settings );
return new WP_REST_Response( array( 'success' => true, 'message' => __( 'Backup settings saved successfully.', 'custom-db-backup' ) ), 200 );
}
/**
* Schedules or reschedules the WP-Cron job for backups.
*/
function custom_db_backup_schedule_cron( $settings = null ) {
if ( $settings === null ) {
$settings = get_option( 'custom_db_backup_settings', array() );
}
// Clear any existing scheduled events
wp_clear_scheduled_hook( 'custom_db_backup_trigger' );
$frequency = $settings['backup_frequency'] ?? 'daily';
$time = $settings['backup_time'] ?? '02:00';
$schedule = 'daily'; // Default schedule interval
switch ( $frequency ) {
case 'weekly':
$schedule = 'weekly';
break;
case 'monthly':
$schedule = 'monthly';
break;
}
// Calculate the next run time based on the specified time and frequency
$next_run = wp_next_scheduled( $schedule );
if ( ! $next_run ) {
// If no schedule exists, create one.
// We need to parse the time and combine it with today's date or the next occurrence of the schedule.
$today = current_time( 'Y-m-d' );
$datetime_str = $today . ' ' . $time . ':00';
$next_run_timestamp = strtotime( $datetime_str );
// Ensure the timestamp is in the future relative to the schedule interval
if ( $next_run_timestamp < time() ) {
// If the time has already passed today, schedule for the next occurrence of the interval
// e.g., if daily and time is 02:00, and current time is 03:00, schedule for tomorrow 02:00.
// If weekly and time is 02:00 on Monday, and current time is Tuesday 03:00, schedule for next Monday 02:00.
// This logic can get complex depending on exact requirements. A simpler approach is to rely on WP-Cron's interval.
// For simplicity here, we'll let WP-Cron handle the interval and just set the time.
// A more robust solution would involve calculating the exact timestamp.
// For now, let's assume WP-Cron's interval is sufficient and we just need to set the time.
// A better approach for specific times:
$next_run_timestamp = custom_db_backup_calculate_next_run( $time, $schedule );
}
wp_schedule_event( $next_run_timestamp, $schedule, 'custom_db_backup_trigger' );
}
}
/**
* Helper to calculate the next run timestamp based on time and schedule.
*/
function custom_db_backup_calculate_next_run( $time_str, $schedule ) {
$now = current_time( 'timestamp' );
list( $hour, $minute ) = explode( ':', $time_str );
$target_timestamp = strtotime( date( 'Y-m-d', $now ) . " {$hour}:{$minute}:00" );
if ( $target_timestamp <= $now ) {
// If the target time has passed today, schedule for the next interval.
switch ( $schedule ) {
case 'daily':
$target_timestamp = strtotime( '+1 day', $target_timestamp );
break;
case 'weekly':
$target_timestamp = strtotime( '+1 week', $target_timestamp );
break;
case 'monthly':
$target_timestamp = strtotime( '+1 month', $target_timestamp );
break;
}
}
return $target_timestamp;
}
// Initial scheduling when the plugin is activated.
register_activation_hook( __FILE__, 'custom_db_backup_activate' );
function custom_db_backup_activate() {
$settings = get_option( 'custom_db_backup_settings', array() );
if ( empty( $settings ) ) {
// Set default settings if none exist
$settings = array(
'backup_frequency' => 'daily',
'backup_time' => '02:00',
'backup_retention' => 7,
'enable_email_notifications' => false,
'email_address' => '',
);
update_option( 'custom_db_backup_settings', $settings );
}
custom_db_backup_schedule_cron( $settings );
}
// Clear schedule on deactivation.
register_deactivation_hook( __FILE__, 'custom_db_backup_deactivate' );
function custom_db_backup_deactivate() {
wp_clear_scheduled_hook( 'custom_db_backup_trigger' );
delete_option( 'custom_db_backup_settings' );
}
[/php]
Next, we need the function that will be triggered by WP-Cron to perform the backup. This function will export the database, save it to a file, and handle cleanup based on retention settings.
[php]
/**
* The actual backup function triggered by WP-Cron.
*/
function custom_db_backup_trigger_backup() {
$settings = get_option( 'custom_db_backup_settings', array() );
if ( empty( $settings ) ) {
// No settings found, do nothing.
return;
}
$upload_dir = wp_upload_dir();
$backup_dir = trailingslashit( $upload_dir['basedir'] ) . 'custom-db-backups/';
// Ensure backup directory exists
if ( ! wp_mkdir_p( $backup_dir ) ) {
error_log( 'Custom DB Backup: Failed to create backup directory: ' . $backup_dir );
return;
}
global $wpdb;
$filename_date = date( 'Y-m-d_H-i-s' );
$backup_filename = "db_backup_{$filename_date}.sql";
$backup_filepath = trailingslashit( $backup_dir ) . $backup_filename;
// Get all table names
$tables = $wpdb->get_col( "SHOW TABLES" );
$output = "-- WordPress DB Backup: {$filename_date}\n";
$output .= "-- Generated by Custom DB Backup Plugin\n\n";
// Loop through each table and get its structure and data
foreach ( $tables as $table ) {
$result = $wpdb->get_results( "SHOW CREATE TABLE {$table}", ARRAY_A );
$output .= "--\n-- Table structure for table `{$table}`\n--\n\n";
$output .= $result[0]['Create Table'] . ";\n\n";
$rows = $wpdb->get_results( "SELECT * FROM {$table}" );
if ( $rows ) {
$output .= "--\n-- Dumping data for table `{$table}`\n--\n\n";
$output .= "INSERT INTO `{$table}` VALUES\n";
$values = array();
foreach ( $rows as $row ) {
$row_values = array();
foreach ( $row as $key => $value ) {
// Properly escape values for SQL INSERT statements
if ( is_null( $value ) ) {
$row_values[] = 'NULL';
} else {
$row_values[] = $wpdb->prepare( '%s', $value );
}
}
$values[] = '(' . implode( ', ', $row_values ) . ')';
}
$output .= implode( ",\n", $values ) . ";\n\n";
}
}
// Save the backup to a file
if ( ! file_put_contents( $backup_filepath, $output ) ) {
error_log( 'Custom DB Backup: Failed to write backup file: ' . $backup_filepath );
return;
}
// Clean up old backups
custom_db_backup_cleanup_old_backups( $backup_dir, $settings['backup_retention'] ?? 7 );
// Send email notification if enabled
if ( ! empty( $settings['enable_email_notifications'] ) && ! empty( $settings['email_address'] ) && is_email( $settings['email_address'] ) ) {
custom_db_backup_send_notification_email( $backup_filepath, $settings['email_address'] );
}
}
add_action( 'custom_db_backup_trigger', 'custom_db_backup_trigger_backup' );
/**
* Cleans up old backup files.
*/
function custom_db_backup_cleanup_old_backups( $backup_dir, $retention_days ) {
if ( ! is_dir( $backup_dir ) || $retention_days <= 0 ) {
return;
}
$files = glob( $backup_dir . 'db_backup_*.sql' );
if ( empty( $files ) ) {
return;
}
rsort( $files ); // Sort by modification time, newest first
$cutoff_time = time() - ( $retention_days * DAY_IN_SECONDS );
foreach ( $files as $file ) {
if ( filemtime( $file ) < $cutoff_time ) {
unlink( $file );
}
}
}
/**
* Sends an email notification about the backup.
*/
function custom_db_backup_send_notification_email( $backup_filepath, $email_address ) {
$subject = sprintf( __( '[%s] Database Backup Successful', 'custom-db-backup' ), get_bloginfo( 'name' ) );
$message = sprintf( __( 'A database backup was successfully created at %s.', 'custom-db-backup' ), current_time( 'mysql' ) );
$message .= "\n\n" . sprintf( __( 'Backup file: %s', 'custom-db-backup' ), basename( $backup_filepath ) );
// You might want to attach the file, but be cautious with large files.
// For simplicity, we're just sending a notification.
$headers = array( 'Content-Type: text/plain; charset=UTF-8' );
wp_mail( $email_address, $subject, $message, $headers );
}
[/php]
In the backend logic:
- We retrieve the saved settings using
get_option(). - The backup directory is created within the WordPress uploads folder.
- We iterate through all tables in the database, generating SQL statements for their structure and data.
$wpdb->prepare()is used for security when inserting data.- The generated SQL is saved to a timestamped
.sqlfile. custom_db_backup_cleanup_old_backups()removes files older than the specified retention period.custom_db_backup_send_notification_email()sends an email if configured.- The
custom_db_backup_triggerhook is added to WP-Cron. - Activation and deactivation hooks ensure the cron job is scheduled and cleared appropriately.
Testing and Refinements
After activating the plugin and building the assets, you should see the “Custom DB Backup Engine” block in the Gutenberg editor. Add it to a post or page and configure the settings in the sidebar. Save the settings and check your browser’s developer console for the “Saving backup settings” log. Then, manually trigger the cron job for testing:
[shell] # In your WordPress root directory wp cron event run custom_db_backup_trigger --due-now [/shell]
Verify that a .sql file is created in wp-content/uploads/custom-db-backups/ and that old files are cleaned up according to your retention settings. Check your email if notifications are enabled.
Further refinements could include:
- More robust error handling and logging.
- Options for backup compression (e.g., Gzip).
- Integration with cloud storage services (S3, Google Drive).
- A dedicated admin page for managing backups and viewing logs, rather than relying solely on the Gutenberg block.
- More sophisticated scheduling options beyond daily/weekly/monthly.
- Security considerations for storing backups, especially if they contain sensitive data. Ensure the backup directory is not publicly accessible.