EveAI Sync WordPress Plugin – Developer Documentation

Table of Contents

• Architecture Overview
• Core Components
• Data Flow
• Class Reference
• WordPress Integration Points
• API Communication
• Metadata Management
• Error Handling
• Development Guidelines

Architecture Overview

The EveAI Sync plugin is built using an object-oriented architecture that follows WordPress plugin development best practices. It consists of several key components that work together to synchronize WordPress content with the EveAI platform.

Main Plugin Structure

eveai_sync/
├── admin/
│   ├── css/
│   └── js/
├── includes/
│   ├── class-eveai-admin.php
│   ├── class-eveai-api.php
│   ├── class-eveai-bulk-sync.php
│   ├── class-eveai-post-handler.php
│   └── class-eveai-sync.php
└── eveai_sync.php

Core Components

1. Main Plugin Class (EveAI_Sync)

The EveAI_Sync class serves as the main plugin orchestrator. It:

• Initializes the plugin components
• Sets up WordPress hooks and actions
• Manages dependencies between components
• Located in includes/class-eveai-sync.php

2. API Handler (EveAI_API)

The EveAI_API class manages all communication with the EveAI platform:

• Handles authentication and token management
• Provides methods for document operations (add, update, delete)
• Implements automatic token refresh
• Located in includes/class-eveai-api.php

3. Post Handler (EveAI_Post_Handler)

The EveAI_Post_Handler class manages WordPress post operations:

• Handles post save/update events
• Manages synchronization logic
• Controls metadata storage
• Located in includes/class-eveai-post-handler.php

4. Admin Interface (EveAI_Admin)

The EveAI_Admin class manages the WordPress admin interface:

• Creates settings pages
• Handles bulk operations
• Manages plugin configuration
• Located in includes/class-eveai-admin.php

Data Flow

Sync Process Flow

1. Post Creation/Update

   WordPress Post Save
   → EveAI_Post_Handler::handle_post_save()
   → Check should_sync_post()
   → prepare_post_data()
   → EveAI_API::add_url() or refresh_document()
   → Store metadata
   
   

Authentication Flow

1. Token Management

   API Request
   → Check token validity
   → If invalid/expired:
     → Request new token
     → Store new token
   → Proceed with request
   
   

Class Reference

EveAI_Sync

class EveAI_Sync {
    // Initializes plugin components
    public function init()

    // Loads required dependencies
    private function load_dependencies()

    // Sets up WordPress actions and filters
    private function setup_actions()
}

EveAI_API

class EveAI_API {
    // Core API methods
    public function add_url($data)
    public function update_document($document_id, $data)
    public function invalidate_document($document_id)
    public function refresh_document($document_id)

    // Token management
    private function ensure_valid_token()
    private function get_new_token()
}

EveAI_Post_Handler

class EveAI_Post_Handler {
    // Post management methods
    public function handle_post_save($post_id, $post, $update)
    public function sync_post($post_id, $is_update)
    public function handle_post_delete($post_id)

    // Helper methods
    private function prepare_post_data($post_id)
    private function should_sync_post($post_id)
}

WordPress Integration Points

Actions

The plugin hooks into several WordPress actions:

// Post management
add_action('save_post', array($post_handler, 'handle_post_save'), 10, 3);
add_action('before_delete_post', array($post_handler, 'handle_post_delete'));

// Admin interface
add_action('admin_init', array($admin, 'register_settings'));
add_action('admin_menu', array($admin, 'add_admin_menu'));

// Meta boxes
add_action('add_meta_boxes', array($admin, 'add_sync_meta_box'));

Metadata

The plugin stores several metadata keys:

• _eveai_document_id: EveAI document identifier
• _eveai_document_version_id: Document version identifier
• _eveai_exclude_sync: Flag to exclude from sync
• _eveai_syncing: Temporary flag during sync process

API Communication

Document Operations

// Adding new document
$response = $this->make_request('POST', '/api/v1/documents/add_url', [
    'url' => get_permalink($post_id),
    'name' => $post->post_title,
    'language' => get_option('eveai_default_language', 'en'),
    // ... additional metadata
]);

// Refreshing existing document
$response = $this->make_request('POST', "/api/v1/documents/{$document_id}/refresh");

Authentication

$response = wp_remote_post($this->api_url . '/api/v1/auth/token', [
    'body' => json_encode([
        'tenant_id' => $this->tenant_id,
        'api_key' => $this->api_key,
    ]),
    'headers' => [
        'Content-Type' => 'application/json',
    ],
]);

Metadata Management

Post Metadata Structure

// Document identification
_eveai_document_id          => '12345'
_eveai_document_version_id  => '67890'

// Sync control
_eveai_exclude_sync        => '1'  // Excludes from sync
_eveai_syncing            => '1'  // Temporary sync flag

Settings Structure

eveai_api_url              // API endpoint URL
eveai_tenant_id           // Tenant identifier
eveai_api_key             // API authentication key
eveai_default_language    // Default content language
eveai_excluded_categories // Excluded category list
eveai_catalog_id          // Catalog identifier

Error Handling

The plugin implements comprehensive error handling:

API Errors

try {
    $response = $this->make_request($method, $endpoint, $data);
} catch (Exception $e) {
    error_log('EveAI Sync Error: ' . $e->getMessage());
    add_action('admin_notices', function() use ($e) {
        echo '<div class="notice notice-error is-dismissible">';
        echo '<p>EveAI Sync Error: ' . esc_html($e->getMessage()) . '</p>';
        echo '</div>';
    });
}

Sync Process Errors

if (!$this->should_sync_post($post_id)) {
    return;
}

try {
    $this->sync_post($post_id, $update);
} catch (Exception $e) {
    error_log('EveAI Sync Error: ' . $e->getMessage());
    // Handle error appropriately
}

Development Guidelines

Adding New Features

1. Extend Existing Classes

   class My_New_Feature extends EveAI_Base {
       public function initialize() {
           // Add WordPress hooks
           add_action('my_new_action', [$this, 'handle_action']);
       }
   }
   
   

2. Register with Main Plugin

   class EveAI_Sync {
       private function load_dependencies() {
           require_once 'class-my-new-feature.php';
           $this->new_feature = new My_New_Feature();
       }
   }
   
   

Best Practices

1. Error Handling
   • Always use try-catch blocks for API operations
   • Log errors appropriately using error_log()
   • Display user-friendly messages using admin notices
2. Security
   • Validate and sanitize all input
   • Use WordPress nonces for form submissions
   • Follow WordPress coding standards for escaping output
3. Performance
   • Use WordPress transients for caching where appropriate
   • Implement batch processing for bulk operations
   • Minimize API calls by bundling operations
4. Testing
   • Test with various WordPress versions
   • Verify compatibility with different PHP versions
   • Check behavior with different post types and taxonomies

Debugging Tips

1. Enable WordPress Debug Mode

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

2. Log API Interactions

   error_log('EveAI API Request: ' . print_r($request, true));
   error_log('EveAI API Response: ' . print_r($response, true));
   
   

3. Monitor Sync Process