Developer Guide

This guide provides technical information for developers who want to extend WP Rollback, integrate it with other tools, or understand its internal architecture.

Architecture Overview

Plugin Structure

WP Rollback follows a modular architecture with clear separation of concerns:

wp-rollback/
├── packages/
│   ├── free-plugin/          # Free version
│   ├── pro-plugin/           # Pro version
│   └── shared-core/          # Shared functionality

Core Components

Service Providers: Manage plugin initialization and dependencies
REST API: Handles rollback requests and data retrieval
Rollback Manager: Orchestrates the rollback process
Step System: Modular rollback steps (backup, download, install, cleanup)
Asset Management: Handles frontend assets and UI components

Development Environment Setup

Requirements

Node.js 16+ and Bun package manager
PHP 7.4+ with Composer
WordPress development environment
Git for version control

Local Development Setup

bash

# Clone the repository
git clone https://github.com/BeyondGoodIO/wp-rollback.git
cd wp-rollback

# Install dependencies
bun install
composer install

# Start development build
bun run dev

Build Commands

bash

# Development build with watching
bun run dev

# Production build
bun run build

# Build specific packages
bun run free:build
bun run pro:build
bun run core:build

API Reference

REST API Endpoints

Get Plugin Information

http

GET /wp-json/wp-rollback/v1/plugin-info

Parameters:

slug (string): Plugin slug
version (string, optional): Specific version

Response:

json

{
  "success": true,
  "data": {
    "slug": "plugin-name",
    "versions": ["1.0.0", "1.1.0", "1.2.0"],
    "current_version": "1.2.0",
    "latest_version": "1.2.0"
  }
}

Process Rollback

http

POST /wp-json/wp-rollback/v1/process-rollback

Parameters:

type (string): "plugin" or "theme"
slug (string): Plugin/theme slug
version (string): Target version
nonce (string): Security nonce

Response:

json

{
  "success": true,
  "data": {
    "message": "Rollback completed successfully",
    "steps": [
      {
        "step": "backup",
        "status": "completed",
        "message": "Backup created"
      }
    ]
  }
}

Get Rollback Steps

http

GET /wp-json/wp-rollback/v1/rollback-steps

Response:

json

{
  "success": true,
  "data": {
    "steps": [
      {
        "id": "backup",
        "name": "Create Backup",
        "description": "Creates backup of current version"
      }
    ]
  }
}

Hooks and Filters

Action Hooks

Pre-Rollback Actions

php

/**
 * Fired before a rollback begins
 *
 * @param string $type Plugin or theme
 * @param string $slug Asset slug
 * @param string $version Target version
 */
do_action('wp_rollback_before_rollback', $type, $slug, $version);

Post-Rollback Actions

php

/**
 * Fired after a rollback completes
 *
 * @param string $type Plugin or theme
 * @param string $slug Asset slug
 * @param string $version Target version
 * @param bool $success Whether rollback succeeded
 */
do_action('wp_rollback_after_rollback', $type, $slug, $version, $success);

Step-Level Actions

php

/**
 * Fired before each rollback step
 *
 * @param string $step_id Step identifier
 * @param array $context Rollback context
 */
do_action('wp_rollback_before_step', $step_id, $context);

/**
 * Fired after each rollback step
 *
 * @param string $step_id Step identifier
 * @param array $context Rollback context
 * @param bool $success Whether step succeeded
 */
do_action('wp_rollback_after_step', $step_id, $context, $success);

Filter Hooks

Modify Rollback Steps

php

/**
 * Filter the rollback steps
 *
 * @param array $steps Available rollback steps
 * @param string $type Plugin or theme
 * @param string $slug Asset slug
 */
$steps = apply_filters('wp_rollback_steps', $steps, $type, $slug);

Modify Version List

php

/**
 * Filter available versions
 *
 * @param array $versions Available versions
 * @param string $slug Asset slug
 * @param string $type Plugin or theme
 */
$versions = apply_filters('wp_rollback_versions', $versions, $slug, $type);

Customize Safety Checks

php

/**
 * Filter safety check results
 *
 * @param bool $safe Whether rollback is safe
 * @param string $slug Asset slug
 * @param string $version Target version
 */
$safe = apply_filters('wp_rollback_safety_check', $safe, $slug, $version);

Custom Rollback Steps

Creating Custom Steps

php

<?php

use WPRollback\Core\Contracts\RollbackStep;
use WPRollback\Core\Contracts\RollbackStepResult;

class CustomRollbackStep implements RollbackStep {
    
    public function get_id(): string {
        return 'custom_step';
    }
    
    public function get_name(): string {
        return 'Custom Step';
    }
    
    public function get_description(): string {
        return 'Performs custom rollback operations';
    }
    
    public function execute(array $context): RollbackStepResult {
        // Custom step logic here
        
        return new RollbackStepResult(
            true, // success
            'Custom step completed successfully',
            $context
        );
    }
    
    public function get_dependencies(): array {
        return ['backup']; // Depends on backup step
    }
}

Registering Custom Steps

php

add_action('wp_rollback_register_steps', function($registerer) {
    $registerer->register(new CustomRollbackStep());
});

Extending the UI

React Components

WP Rollback uses React for its frontend interface. You can extend the UI by creating custom components:

jsx

// custom-rollback-component.jsx
import { useState } from 'react';
import { Button } from '@wordpress/components';

export const CustomRollbackComponent = ({ plugin, onRollback }) => {
    const [loading, setLoading] = useState(false);
    
    const handleRollback = async (version) => {
        setLoading(true);
        try {
            await onRollback(plugin.slug, version);
        } finally {
            setLoading(false);
        }
    };
    
    return (
        <div className="custom-rollback-component">
            <h3>Custom Rollback Options</h3>
            {plugin.versions.map(version => (
                <Button
                    key={version}
                    variant="secondary"
                    onClick={() => handleRollback(version)}
                    disabled={loading}
                >
                    Rollback to {version}
                </Button>
            ))}
        </div>
    );
};

Enqueueing Custom Assets

php

add_action('wp_enqueue_scripts', function() {
    if (is_admin() && isset($_GET['page']) && $_GET['page'] === 'wp-rollback') {
        wp_enqueue_script(
            'custom-rollback-script',
            plugins_url('assets/custom-rollback.js', __FILE__),
            ['wp-rollback-app'],
            '1.0.0',
            true
        );
    }
});

Database Schema

Core Tables

WP Rollback uses WordPress options for most data storage:

sql

-- Plugin metadata
wp_options.option_name = 'wp_rollback_plugin_meta'
wp_options.option_value = '{"plugin_slug": {"current_version": "1.0.0"}}'

-- Rollback history (Pro)
wp_options.option_name = 'wp_rollback_history'
wp_options.option_value = '[{"timestamp": 1234567890, "action": "rollback"}]'

Custom Tables (Pro)

The Pro version may create additional tables:

sql

CREATE TABLE wp_rollback_activity_log (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    user_id bigint(20) NOT NULL,
    action varchar(50) NOT NULL,
    asset_type varchar(20) NOT NULL,
    asset_slug varchar(100) NOT NULL,
    from_version varchar(50) DEFAULT NULL,
    to_version varchar(50) NOT NULL,
    status varchar(20) NOT NULL,
    message text DEFAULT NULL,
    created_at datetime NOT NULL,
    PRIMARY KEY (id),
    KEY user_id (user_id),
    KEY asset_type (asset_type),
    KEY created_at (created_at)
);

Integration Examples

Slack Notifications

php

add_action('wp_rollback_after_rollback', function($type, $slug, $version, $success) {
    if ($success) {
        $message = "✅ {$type} '{$slug}' rolled back to version {$version}";
    } else {
        $message = "❌ Failed to rollback {$type} '{$slug}' to version {$version}";
    }
    
    wp_remote_post('https://hooks.slack.com/your-webhook-url', [
        'body' => json_encode([
            'text' => $message,
            'channel' => '#deployments'
        ]),
        'headers' => [
            'Content-Type' => 'application/json'
        ]
    ]);
});

Custom Logging

php

class CustomRollbackLogger {
    
    public function __construct() {
        add_action('wp_rollback_before_rollback', [$this, 'log_rollback_start'], 10, 3);
        add_action('wp_rollback_after_rollback', [$this, 'log_rollback_end'], 10, 4);
    }
    
    public function log_rollback_start($type, $slug, $version) {
        error_log("WP Rollback: Starting rollback of {$type} '{$slug}' to version {$version}");
    }
    
    public function log_rollback_end($type, $slug, $version, $success) {
        $status = $success ? 'SUCCESS' : 'FAILED';
        error_log("WP Rollback: Rollback of {$type} '{$slug}' to version {$version} - {$status}");
    }
}

new CustomRollbackLogger();

Custom Workflow Integration

php

add_action('wp_rollback_after_rollback', function($type, $slug, $version, $success) {
    if ($success) {
        // Log rollback to custom system
        error_log("Rollback completed: {$type} '{$slug}' to version {$version}");
        
        // Optional: Custom deployment hook
        // do_action('custom_deployment_hook', $type, $slug, $version);
    }
});

Permission Checks

php

// Verify user capabilities
add_filter('wp_rollback_can_rollback', function($can_rollback, $type, $slug) {
    if ($type === 'plugin' && !current_user_can('activate_plugins')) {
        return false;
    }
    
    if ($type === 'theme' && !current_user_can('switch_themes')) {
        return false;
    }
    
    return $can_rollback;
}, 10, 3);

Contributing

Code Standards

Follow WordPress PHP coding standards
Use PSR-4 autoloading for classes
Write comprehensive PHPDoc comments
Include unit tests for new features

Submission Process

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

Development Workflow

bash

# Install dependencies
bun install && composer install

# Run tests
composer test

# Run linting
bun run lint

# Build for production
bun run build

Troubleshooting Development Issues

Common Problems

Build Errors

bash

# Clear cache and reinstall
rm -rf node_modules bun.lockb
bun install

# Rebuild packages
bun run clean && bun run build

Next Steps

Check the Troubleshooting Guide for common development issues
Explore the Pro Features for advanced integration options

Developer Guide ​

Architecture Overview ​

Plugin Structure ​

Core Components ​

Development Environment Setup ​

Requirements ​

Local Development Setup ​

Build Commands ​

API Reference ​

REST API Endpoints ​

Get Plugin Information ​

Process Rollback ​

Get Rollback Steps ​

Hooks and Filters ​

Action Hooks ​

Pre-Rollback Actions ​

Post-Rollback Actions ​

Step-Level Actions ​

Filter Hooks ​

Modify Rollback Steps ​

Modify Version List ​

Customize Safety Checks ​

Custom Rollback Steps ​

Creating Custom Steps ​

Registering Custom Steps ​

Extending the UI ​

React Components ​

Enqueueing Custom Assets ​

Database Schema ​

Core Tables ​

Custom Tables (Pro) ​

Integration Examples ​

Slack Notifications ​

Custom Logging ​

Custom Workflow Integration ​

Permission Checks ​

Contributing ​

Code Standards ​

Submission Process ​

Development Workflow ​

Troubleshooting Development Issues ​

Common Problems ​

Build Errors ​

Next Steps ​

Developer Guide

Architecture Overview

Plugin Structure

Core Components

Development Environment Setup

Requirements

Local Development Setup

Build Commands

API Reference

REST API Endpoints

Get Plugin Information

Process Rollback

Get Rollback Steps

Hooks and Filters

Action Hooks

Pre-Rollback Actions

Post-Rollback Actions

Step-Level Actions

Filter Hooks

Modify Rollback Steps

Modify Version List

Customize Safety Checks

Custom Rollback Steps

Creating Custom Steps

Registering Custom Steps

Extending the UI

React Components

Enqueueing Custom Assets

Database Schema

Core Tables

Custom Tables (Pro)

Integration Examples

Slack Notifications

Custom Logging

Custom Workflow Integration

Permission Checks

Contributing

Code Standards

Submission Process

Development Workflow

Troubleshooting Development Issues

Common Problems

Build Errors

Next Steps