README

Phiên bản: 1.0 Ngày tạo: 2025 Tác giả: Development Team

📋 MỤC LỤC

Tổng quan WordPress Adapter
Mối quan hệ với Rake Core
Kiến trúc Adapter
Database Integration
WordPress Integration
Cách sử dụng
Tài liệu kỹ thuật
Development Guidelines

🎯 TỔNG QUAN WORDPRESS ADAPTER

Mục tiêu

Rake WordPress Adapter là bridge giữa Rake Core Framework và WordPress, cung cấp:

WordPress Database Integration: Adapter cho WordPress database operations
WordPress Hooks Integration: Tích hợp với WordPress hooks system
WordPress Admin Integration: Tích hợp với WordPress admin interface
Security Layer: WordPress security functions integration
Cache Integration: WordPress cache system integration

Vai trò trong hệ thống

┌─────────────────────────────────────────────────────────────┐
│                RAKE WORDPRESS ADAPTER                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │   DATABASE      │  │     HOOKS       │  │    ADMIN    │ │
│  │   ADAPTER       │  │   INTEGRATION   │  │ INTEGRATION │ │
│  │                 │  │                 │  │             │ │
│  │ • WP Database   │  │ • add_action    │  │ • Menu      │ │
│  │ • Query Builder │  │ • add_filter    │  │ • Pages     │ │
│  │ • Prefix Handle │  │ • do_action     │  │ • Scripts   │ │
│  │ • wpdb Wrapper  │  │ • apply_filters │  │ • Styles    │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │    SECURITY     │  │      CACHE      │  │   CONFIG    │ │
│  │     LAYER       │  │   INTEGRATION   │  │ INTEGRATION │ │
│  │                 │  │                 │  │             │ │
│  │ • Nonce Check   │  │ • WP Cache      │  │ • WP Config │ │
│  │ • Capability    │  │ • Transients    │  │ • Options   │ │
│  │ • Sanitization  │  │ • Object Cache  │  │ • Settings  │ │
│  │ • Validation    │  │ • Query Cache   │  │ • Constants │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────┘

🔗 MỐI QUAN HỆ VỚI RAKE CORE

Dependency Chain

┌─────────────────┐    depends on    ┌─────────────────┐
│   CRAWFLOW      │ ────────────────▶ │ RAKE WORDPRESS  │
│   PLUGIN        │                  │    ADAPTER      │
└─────────────────┘                  └─────────────────┘
                                              │
                                              │ depends on
                                              ▼
                                    ┌─────────────────┐
                                    │   RAKE CORE     │
                                    │   FRAMEWORK     │
                                    └─────────────────┘

Interface Implementation

WordPress Adapter implements các interfaces từ Rake Core:

// Database Adapter Interface từ Rake Core
interface DatabaseAdapterInterface
{
    public function query(string $sql): bool;
    public function getResults(string $sql): array;
    public function getRow(string $sql): ?array;
    public function getVar(string $sql): mixed;
    public function insert(string $table, array $data): int;
    public function update(string $table, array $data, array $where): int;
    public function delete(string $table, array $where): int;
    public function getPrefix(): string;
    public function escape(string $value): string;
}

// WordPress Adapter Implementation
class WordPressDatabaseAdapter implements DatabaseAdapterInterface
{
    // Implementation cho WordPress
}

Service Registration

// Trong Rake Container
$container->bind(DatabaseAdapterInterface::class, WordPressDatabaseAdapter::class);
$container->bind(WordPressHooksInterface::class, WordPressHooksAdapter::class);
$container->bind(WordPressAdminInterface::class, WordPressAdminAdapter::class);

🏗️ KIẾN TRÚC ADAPTER

Package Structure

rake-wordpress-adapter/
├── src/
│   ├── Database/              # WordPress Database Integration
│   │   ├── WordPressDatabaseAdapter.php
│   │   ├── WordPressQueryBuilder.php
│   │   └── WordPressPrefixHandler.php
│   ├── Hooks/                 # WordPress Hooks Integration
│   │   ├── WordPressHooksAdapter.php
│   │   └── WordPressHooksInterface.php
│   ├── Admin/                 # WordPress Admin Integration
│   │   ├── WordPressAdminAdapter.php
│   │   ├── WordPressMenuBuilder.php
│   │   └── WordPressScriptManager.php
│   ├── Security/              # WordPress Security Layer
│   │   ├── WordPressSecurityAdapter.php
│   │   ├── WordPressNonceHandler.php
│   │   └── WordPressCapabilityChecker.php
│   ├── Cache/                 # WordPress Cache Integration
│   │   ├── WordPressCacheAdapter.php
│   │   ├── WordPressTransientHandler.php
│   │   └── WordPressObjectCache.php
│   └── Config/                # WordPress Config Integration
│       ├── WordPressConfigAdapter.php
│       └── WordPressOptionsHandler.php
├── composer.json
└── README.md

Package Dependencies

{
    "name": "puleeno/rake-wordpress-adapter",
    "require": {
        "php": ">=8.1",
        "ramphor/rake": "^2.0"
    },
    "autoload": {
        "psr-4": {
            "Rake\\WordPress\\": "src/"
        }
    }
}

🗄️ DATABASE INTEGRATION

WordPress Database Adapter

use Rake\WordPress\Database\WordPressDatabaseAdapter;

$adapter = new WordPressDatabaseAdapter();

// Basic operations
$adapter->insert('posts', [
    'post_title' => 'Test Post',
    'post_content' => 'Test content',
    'post_status' => 'publish'
]);

$posts = $adapter->getResults("SELECT * FROM {$adapter->getPrefix()}posts WHERE post_type = 'post'");

$adapter->update('posts',
    ['post_status' => 'draft'],
    ['ID' => 1]
);

$adapter->delete('posts', ['ID' => 1]);

WordPress Query Builder

use Rake\WordPress\Database\WordPressQueryBuilder;

$query = new WordPressQueryBuilder($adapter);

$posts = $query->select(['ID', 'post_title', 'post_content'])
    ->from('posts')
    ->where('post_type', '=', 'post')
    ->where('post_status', '=', 'publish')
    ->orderBy('post_date', 'DESC')
    ->limit(10)
    ->get();

Prefix Handling

// Tự động xử lý WordPress table prefix
$adapter = new WordPressDatabaseAdapter();
echo $adapter->getPrefix(); // wp_

// Tự động thêm prefix khi cần
$table = $adapter->addPrefix('posts'); // wp_posts

🔧 WORDPRESS INTEGRATION

WordPress Hooks Integration

use Rake\WordPress\Hooks\WordPressHooksAdapter;

$hooks = new WordPressHooksAdapter();

// Add actions
$hooks->addAction('init', [$this, 'initialize']);
$hooks->addAction('wp_loaded', [$this, 'onWpLoaded']);

// Add filters
$hooks->addFilter('the_content', [$this, 'modifyContent']);

// Do actions
$hooks->doAction('custom_action', $data);

// Apply filters
$modified = $hooks->applyFilters('custom_filter', $value);

WordPress Admin Integration

use Rake\WordPress\Admin\WordPressAdminAdapter;

$admin = new WordPressAdminAdapter();

// Add menu pages
$admin->addMenuPage(
    'My Plugin',
    'My Plugin',
    'manage_options',
    'my-plugin',
    [$this, 'renderPage']
);

// Enqueue scripts
$admin->enqueueScript('my-script', '/path/to/script.js');

// Enqueue styles
$admin->enqueueStyle('my-style', '/path/to/style.css');

WordPress Security Layer

use Rake\WordPress\Security\WordPressSecurityAdapter;

$security = new WordPressSecurityAdapter();

// Nonce verification
if ($security->verifyNonce($_POST['nonce'], 'my_action')) {
    // Process form
}

// Capability checking
if ($security->currentUserCan('manage_options')) {
    // Admin action
}

// Data sanitization
$clean = $security->sanitizeTextField($_POST['data']);

🚀 CÁCH SỬ DỤNG

1. Cài đặt

Composer Installation

composer require puleeno/rake-wordpress-adapter

Manual Installation

git clone https://github.com/puleeno/rake-wordpress-adapter.git
cd rake-wordpress-adapter
composer install

2. Khởi tạo với Rake Core

use Rake\Rake;
use Rake\WordPress\Database\WordPressDatabaseAdapter;
use Rake\WordPress\Hooks\WordPressHooksAdapter;
use Rake\WordPress\Admin\WordPressAdminAdapter;

// Tạo Rake container
$app = new Rake();

// Register WordPress adapters
$app->singleton(DatabaseAdapterInterface::class, WordPressDatabaseAdapter::class);
$app->singleton(WordPressHooksInterface::class, WordPressHooksAdapter::class);
$app->singleton(WordPressAdminInterface::class, WordPressAdminAdapter::class);

// Bootstrap
$app->make(WordPressHooksInterface::class);

3. Sử dụng Database Adapter

// Basic CRUD operations
$adapter = new WordPressDatabaseAdapter();

// Insert
$postId = $adapter->insert('posts', [
    'post_title' => 'New Post',
    'post_content' => 'Post content',
    'post_status' => 'publish',
    'post_type' => 'post'
]);

// Select
$posts = $adapter->getResults("
    SELECT * FROM {$adapter->getPrefix()}posts
    WHERE post_type = 'post'
    ORDER BY post_date DESC
    LIMIT 10
");

// Update
$affected = $adapter->update('posts',
    ['post_status' => 'draft'],
    ['ID' => $postId]
);

// Delete
$deleted = $adapter->delete('posts', ['ID' => $postId]);

4. Sử dụng Hooks Adapter

$hooks = new WordPressHooksAdapter();

// Register plugin hooks
$hooks->addAction('plugins_loaded', function() {
    // Plugin initialization
});

$hooks->addAction('admin_menu', function() {
    // Add admin menu
});

$hooks->addFilter('the_title', function($title) {
    return 'Modified: ' . $title;
});

5. Sử dụng Admin Adapter

$admin = new WordPressAdminAdapter();

// Add admin menu
$admin->addMenuPage(
    'My Plugin',
    'My Plugin',
    'manage_options',
    'my-plugin',
    function() {
        echo '<div class="wrap"><h1>My Plugin</h1></div>';
    }
);

// Enqueue admin assets
$admin->enqueueScript('my-admin-script', '/js/admin.js');
$admin->enqueueStyle('my-admin-style', '/css/admin.css');

6. Sử dụng Security Adapter

$security = new WordPressSecurityAdapter();

// Form processing
if ($_POST && $security->verifyNonce($_POST['nonce'], 'save_data')) {
    if ($security->currentUserCan('manage_options')) {
        $cleanData = $security->sanitizeTextField($_POST['data']);
        // Process data
    }
}

7. Sử dụng Cache Adapter

$cache = new WordPressCacheAdapter();

// Set cache
$cache->set('my_key', $data, 3600); // 1 hour

// Get cache
$data = $cache->get('my_key');

// Delete cache
$cache->delete('my_key');

📚 TÀI LIỆU KỸ THUẬT

Tài liệu chi tiết

📖 docs/technical-documentation.md

Nội dung:

WordPress Database Integration
WordPress Hooks Integration
WordPress Admin Integration
Security Layer
Cache Integration
Development Guidelines

Code Examples

Database Operations

// Transaction handling
$adapter->beginTransaction();
try {
    $adapter->insert('posts', $postData);
    $adapter->insert('postmeta', $metaData);
    $adapter->commit();
} catch (Exception $e) {
    $adapter->rollback();
    throw $e;
}

Hook Integration

// Custom hooks
$hooks->addAction('my_custom_hook', function($data) {
    // Process data
});

$hooks->doAction('my_custom_hook', $data);

Admin Integration

// Submenu pages
$admin->addSubmenuPage(
    'my-plugin',
    'Settings',
    'Settings',
    'manage_options',
    'my-plugin-settings',
    [$this, 'renderSettings']
);

🛠️ DEVELOPMENT GUIDELINES

Coding Standards

WordPress Integration Best Practices

// Always use WordPress functions with backslash prefix
$result = \wp_verify_nonce($nonce, $action);

// Use WordPress security functions
$sanitized = \sanitize_text_field($input);

// Check capabilities before actions
if (\current_user_can('manage_options')) {
    // Perform admin action
}

// Use WordPress hooks properly
\add_action('init', [$this, 'initialize']);

PSR-12 Compliance

<?php

declare(strict_types=1);

namespace Rake\WordPress\Database;

use Rake\Database\DatabaseAdapterInterface;

class WordPressDatabaseAdapter implements DatabaseAdapterInterface
{
    private \wpdb $wpdb;
    private string $prefix;

    public function __construct()
    {
        global $wpdb;
        $this->wpdb = $wpdb;
        $this->prefix = $wpdb->prefix;
    }

    public function query(string $sql): bool
    {
        return $this->wpdb->query($sql) !== false;
    }
}

Testing Guidelines

Unit Testing

class WordPressDatabaseAdapterTest extends TestCase
{
    private WordPressDatabaseAdapter $adapter;

    protected function setUp(): void
    {
        $this->adapter = new WordPressDatabaseAdapter();
    }

    public function testInsert(): void
    {
        // Arrange
        $data = ['post_title' => 'Test Post'];

        // Act
        $id = $this->adapter->insert('posts', $data);

        // Assert
        $this->assertGreaterThan(0, $id);
    }
}

Integration Testing

class WordPressIntegrationTest extends TestCase
{
    public function testDatabaseAdapter(): void
    {
        // Arrange
        $adapter = new WordPressDatabaseAdapter();

        // Act
        $result = $adapter->query('SELECT 1');

        // Assert
        $this->assertTrue($result);
    }
}

Error Handling

class WordPressException extends Exception
{
    public function __construct(string $message, array $context = [], int $code = 0, ?Throwable $previous = null)
    {
        parent::__construct("WordPress error: {$message}", $code, $previous);
    }
}

// Usage
try {
    $adapter = new WordPressDatabaseAdapter();
    $result = $adapter->insert('table', $data);
} catch (WordPressException $e) {
    Logger::error('WordPress operation failed: ' . $e->getMessage());
}

🔧 CONFIGURATION

WordPress Settings

Adapter tự động sử dụng WordPress database settings:

// Tự động detect từ WordPress
$adapter = new WordPressDatabaseAdapter();
echo $adapter->getPrefix();        // wp_
echo $adapter->getCharset();       // utf8mb4
echo $adapter->getCollation();     // utf8mb4_unicode_ci

Custom Configuration

// Nếu cần custom settings
$adapter = new WordPressDatabaseAdapter();

// Custom database operations
$adapter->query("SET SESSION sql_mode = 'NO_AUTO_VALUE_ON_ZERO'");

🚨 TROUBLESHOOTING

Common Issues

Error: `Class 'Rake\WordPress\Database\WordPressDatabaseAdapter' not found`

Solution:

composer dump-autoload

Error: `WordPress not loaded`

Solution:

// Ensure WordPress is loaded
require_once 'wp-load.php';

Error: `Database connection failed`

Solution:

Check WordPress database configuration
Verify database credentials
Check database server status

Debug Mode

// Enable debug mode
$adapter = new WordPressDatabaseAdapter();

// Check last error
echo $adapter->getLastError();

// Check affected rows
echo $adapter->affectedRows();

📊 PERFORMANCE

Optimizations

Prepared statements: Sử dụng WordPress prepared statements
Connection reuse: Tái sử dụng WordPress database connection
Query optimization: Tối ưu queries cho WordPress
Memory management: Efficient memory usage

Best Practices

// Use transactions for multiple operations
$adapter->beginTransaction();
try {
    foreach ($posts as $post) {
        $adapter->insert('posts', $post);
    }
    $adapter->commit();
} catch (Exception $e) {
    $adapter->rollback();
    throw $e;
}

// Use batch operations
$adapter->getResults("SELECT * FROM posts LIMIT 1000");

// Use specific columns
$adapter->getResults("SELECT ID, post_title FROM posts WHERE post_type = 'post'");

🎯 KẾT LUẬN

Rake WordPress Adapter cung cấp bridge hoàn chỉnh giữa Rake Core Framework và WordPress với:

Điểm nổi bật:

Database Integration: WordPress database adapter với prefix handling
Hooks Integration: WordPress hooks system integration
Admin Integration: WordPress admin interface integration
Security Layer: WordPress security functions integration
Cache Integration: WordPress cache system integration

Sử dụng:

// Initialize adapter
$adapter = new WordPressDatabaseAdapter();
$hooks = new WordPressHooksAdapter();
$admin = new WordPressAdminAdapter();

// Use database
$results = $adapter->getResults('SELECT * FROM wp_posts');

// Use hooks
$hooks->addAction('init', [$this, 'initialize']);

// Use admin
$admin->addMenuPage('My Plugin', 'My Plugin', 'manage_options', 'my-plugin', [$this, 'renderPage']);

Tài liệu này sẽ được cập nhật thường xuyên khi có thay đổi trong adapter.

puleeno / rake-wordpress-adapter

Maintainers

Details

README

📋 MỤC LỤC

🎯 TỔNG QUAN WORDPRESS ADAPTER

Mục tiêu

Vai trò trong hệ thống

🔗 MỐI QUAN HỆ VỚI RAKE CORE

Dependency Chain

Interface Implementation

Service Registration

🏗️ KIẾN TRÚC ADAPTER

Package Structure

Package Dependencies

🗄️ DATABASE INTEGRATION

WordPress Database Adapter

WordPress Query Builder

Prefix Handling

🔧 WORDPRESS INTEGRATION

WordPress Hooks Integration

WordPress Admin Integration

WordPress Security Layer

🚀 CÁCH SỬ DỤNG

1. Cài đặt

Composer Installation

Manual Installation

2. Khởi tạo với Rake Core

3. Sử dụng Database Adapter

4. Sử dụng Hooks Adapter

5. Sử dụng Admin Adapter

6. Sử dụng Security Adapter

7. Sử dụng Cache Adapter

📚 TÀI LIỆU KỸ THUẬT

Tài liệu chi tiết

Code Examples

Database Operations

Hook Integration

Admin Integration

🛠️ DEVELOPMENT GUIDELINES

Coding Standards

WordPress Integration Best Practices

PSR-12 Compliance

Testing Guidelines

Unit Testing

Integration Testing

Error Handling

🔧 CONFIGURATION

WordPress Settings

Custom Configuration

🚨 TROUBLESHOOTING

Common Issues

Error: Class 'Rake\WordPress\Database\WordPressDatabaseAdapter' not found

Error: WordPress not loaded

Error: Database connection failed

Debug Mode

📊 PERFORMANCE

Optimizations

Best Practices

🎯 KẾT LUẬN

Điểm nổi bật:

Sử dụng:

Error: `Class 'Rake\WordPress\Database\WordPressDatabaseAdapter' not found`

Error: `WordPress not loaded`

Error: `Database connection failed`