# wp-falcon5

**Repository Path**: ceiba/wp-falcon5

## Basic Information

- **Project Name**: wp-falcon5
- **Description**: No description available
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-07
- **Last Updated**: 2025-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Falcon5 WordPress Plugin
## 常量定义


- define('FC5_TRANS_MASTER_PAGE_CACHE',false) // 翻译时，是否上传源页面缓存


## 架构说明

Falcon5 是一个 WordPress 插件，用于提供多语言翻译功能。本文档主要介绍插件的架构设计和使用方法。

### 数据库迁移

插件使用 Phinx 进行数据库迁移管理。迁移脚本位于 `db/migrations` 目录中，通过 `phinx.php` 配置文件进行管理。

#### 表前缀

插件使用 WordPress 的表前缀来创建和管理数据表，确保在多站点环境下也能正常工作。所有插件创建的表都以 `{wp_prefix}fc5_` 开头，例如 `wp_fc5_cache` 或多站点环境下的 `wp_2_fc5_cache`。

表前缀的获取采用了简单的检测机制：
1. 如果在 WordPress 环境中运行，直接使用 `$wpdb->prefix`，这在多站点环境中也能正确获取当前站点的表前缀
2. 如果不在 WordPress 环境中运行（如命令行执行迁移），使用 `DB_PREFIX` 常量或默认值 `wp_`

##### 多站点环境配置

在多站点环境中，如果需要在非 WordPress 环境下执行迁移，可以在执行命令前定义 `DB_PREFIX` 常量：

```php
// 在执行 Phinx 命令前定义 DB_PREFIX 常量
define('DB_PREFIX', 'wp_2_'); // 替换为目标站点的表前缀
```

这种简单的配置方式确保了插件在各种环境下都能正确获取表前缀，包括多站点环境。

#### 迁移机制

当插件被激活时，会自动执行数据库迁移脚本，创建或更新必要的数据表。迁移记录保存在 `{wp_prefix}phinxlog` 表中，用于跟踪已执行的迁移脚本。

当插件被禁用时，会自动执行数据库回滚操作，删除插件创建的数据表。这确保了插件在禁用后不会在数据库中留下无用的表。

#### 自动修复机制

插件内置了自动修复机制，用于处理各种异常情况：

**激活插件时**：
- 如果发现某个表不存在但 `phinxlog` 中有对应的迁移记录，会自动清除该记录，以便重新执行迁移脚本创建表。

**禁用插件时**：
- 无论 `phinxlog` 表是否存在，都会确保执行回滚操作。
- 如果 `phinxlog` 表不存在，会自动创建该表并添加必要的记录。
- 如果 `phinxlog` 表存在但缺少必要的记录，会自动添加这些记录。

这种简单而可靠的机制确保了插件的数据库操作在各种异常情况下都能正常工作，提高了插件的稳定性和用户体验。

#### 手动重置数据库

如果需要完全重置插件的数据库，可以执行以下步骤：
1. 停用插件
2. 删除所有 `{wp_prefix}fc5_*` 表和 `{wp_prefix}phinxlog` 表
3. 重新激活插件

### 路由系统

插件使用两种路由系统来处理请求：AJAX 路由和 REST API 路由。

#### AJAX 路由

AJAX 路由配置位于 `inc/WPProviders/Route.php` 文件中。

路由配置采用以下格式：

```php
[
    'auth' => [
        'controller' => AuthController::class,
        'routes' => [
            'validate_key' => [
                'method' => 'validateKey',
                'public' => true,
            ],
        ],
    ],
    'entry' => [
        'controller' => GatewayController::class,
        'routes' => [
            'save_entry' => [
                'method' => 'saveEntry',
                'public' => true,
            ],
            'entry_list' => [
                'method' => 'entryList',
                'public' => true,
            ],
            'translate_url' => [
                'method' => 'translateUrl',
                'public' => true,
            ],
        ],
    ],
    'site' => [
        'controller' => 'CacheController',
        'routes' => [
            'cache_list' => [
                'method' => 'list',
                'public' => true,
            ],
            'lock_page' => [
                'method' => 'lockPage',
                'public' => true,
            ],
            'unlock_page' => [
                'method' => 'unlockPage',
                'public' => true,
            ],
        ],
    ],
    'callback' => [
        'controller' => 'CallbackController',
        'routes' => [
            'site_info' => [
                'method' => 'siteInfoCallback',
                'public' => true,
            ],
        ],
    ],
    'settings' => [
        'controller' => 'SettingsController',
        'routes' => [
            'get_settings' => [
                'method' => 'getSettings',
                'public' => false,
            ],
            'save_settings' => [
                'method' => 'saveSettings',
                'public' => false,
            ],
            'get_cache_directory' => [
                'method' => 'getCacheDirectory',
                'public' => false,
            ],
            'validate_domain' => [
                'method' => 'validateDomain',
                'public' => false,
            ],
        ],
    ],
]
```

每个路由配置项包含：
- `controller`：处理请求的控制器类
- `routes`：该控制器处理的路由列表
  - 每个路由包含 `method`（控制器中处理请求的方法名）和 `public`（是否允许未登录用户访问）

#### REST API 路由

REST API 路由配置位于 `inc/WPProviders/RestRoute.php` 文件中。

路由配置采用以下格式：

```php
[
    'callback' => [
        'controller' => \falcon5\inc\Http\Controllers\Rest\CallbackController::class,
        'routes' => [
            'site_info' => [
                'method' => 'siteInfoCallback',
                'public' => true,
            ],
        ],
    ],
    // 其他 REST API 路由配置...
]
```

REST API 路由的配置格式与 AJAX 路由相似，但它们注册为 WordPress REST API 端点，而不是 AJAX 动作。

### 请求处理

插件使用自定义的 `Request` 类来处理请求参数。`Request` 类位于 `inc/Http/Request.php` 文件中。

```php
// 获取请求参数
$value = $request->get('param_name', 'default_value');

// 获取所有 POST 参数
$allParams = $request->all();

// 获取请求方法
$method = $request->getMethod();

// 获取当前动作
$action = $request->getAction();

// 设置请求参数（REST API 请求中使用）
$request->setParam('key', 'value');
```

### 响应格式

插件使用自定义的 `JsonResponse` 类来生成响应。`JsonResponse` 类位于 `inc/Http/JsonResponse.php` 文件中。

```php
// 成功响应
return JsonResponse::success($data);

// 错误响应
return JsonResponse::error($code, $message, $extra);
```

响应格式为：

```json
{
    "code": 1,       // 成功时为 1，失败时为错误代码
    "msg": "success", // 成功或错误消息
    "data": {},      // 响应数据
    "extra": null    // 额外信息
}
```

### 前端使用示例

#### AJAX 请求示例

```javascript
fc5_utils.showLoading();
fc5_utils.post(
    falcon5_ajax_config.ajax_url,
    { action: 'settings_get_settings' },
    function(response) {
        fc5_utils.hideLoading();
        if (response.code === 1 && response.data) {
            // 处理成功响应
            console.log('设置数据:', response.data);
        } else {
            // 处理错误响应
            console.error('获取设置失败:', response.msg);
            fc5_utils.showTip(response.msg || '获取设置失败');
        }
    },
    function(error) {
        fc5_utils.hideLoading();
        console.error('请求失败:', error);
        fc5_utils.showTip(error);
    }
);
```

#### REST API 请求示例

```javascript
fc5_utils.showLoading();
// 构建 REST API URL
const restUrl = falcon5_ajax_config.rest_url + 'falcon5/v1/callback/site_info';

fc5_utils.post(
    restUrl,
    { 
        // REST API 请求参数
        site_id: 123,
        domain: 'example.com'
    },
    function(response) {
        fc5_utils.hideLoading();
        if (response.code === 1 && response.data) {
            // 处理成功响应
            console.log('站点信息:', response.data);
        } else {
            // 处理错误响应
            console.error('获取站点信息失败:', response.msg);
            fc5_utils.showTip(response.msg || '获取站点信息失败');
        }
    },
    function(error) {
        fc5_utils.hideLoading();
        console.error('请求失败:', error);
        fc5_utils.showTip(error);
    }
);
```

#### 使用 admin_app 中的方法

```javascript
// 使用 AJAX 方法
admin_app.getSettings(
    function(data) {
        console.log('设置数据:', data);
    },
    function(error) {
        console.error('获取设置失败:', error);
    }
);

// 使用 REST API 方法
admin_app.getSiteInfo(
    { 
        site_id: 123,
        domain: 'example.com'
    },
    function(data) {
        console.log('站点信息:', data);
    },
    function(error) {
        console.error('获取站点信息失败:', error);
    }
);
```

## REST API 端点

Falcon5 插件提供了以下 REST API 端点：

### 回调 API

基础 URL: `/wp-json/falcon5/v1/callback`

#### 获取站点信息

- **端点**: `/site_info`
- **方法**: POST
- **参数**:
  - `site_id`: 站点 ID
  - `domain`: 站点域名
- **响应**:
  ```json
  {
    "code": 1,
    "msg": "success",
    "data": {
      "site_id": 123,
      "domain": "example.com",
      "status": "active"
    },
    "extra": null
  }
  ```

## 开发指南

### 添加新的控制器

1. 创建一个继承自 `BaseController` 的新控制器类
2. 实现必要的方法
3. 在路由配置中添加相应的路由

### 添加新的 AJAX 路由

在 `Route.php` 的路由配置中添加新的路由项：

```php
'prefix' => [
    'controller' => YourController::class,
    'routes' => [
        'action_name' => [
            'method' => 'methodName',
            'public' => true|false,
        ],
    ],
],
```

### 添加新的 REST API 路由

在 `RestRoute.php` 的路由配置中添加新的路由项：

```php
'prefix' => [
    'controller' => \falcon5\inc\Http\Controllers\Rest\YourController::class,
    'routes' => [
        'endpoint_name' => [
            'method' => 'methodName',
            'public' => true|false,
        ],
    ],
],
```

### 前端调用新的 AJAX 路由

```javascript
fc5_utils.post(
    falcon5_ajax_config.ajax_url,
    { 
        action: 'prefix_action_name',
        // 其他参数
    },
    function(response) {
        // 处理响应
    },
    function(error) {
        // 处理错误
    }
);
```

### 前端调用新的 REST API 路由

```javascript
const restUrl = falcon5_ajax_config.rest_url + 'falcon5/v1/prefix/endpoint_name';

fc5_utils.post(
    restUrl,
    { 
        // 请求参数
    },
    function(response) {
        // 处理响应
    },
    function(error) {
        // 处理错误
    }
);
```

```nginx conf
rewrite ^/(af|sq|am|ar|hy|az|eu|be|bn|bs|bg|ca|ceb|ny|zh-CN|zh-TW|co|hr|cs|da|nl|en|eo|et|tl|fi|fr|fy|gl|ka|de|el|gu|ht|ha|haw|iw|hi|hmn|hu|is|ig|id|ga|it|ja|jw|kn|kk|km|ko|ku|ky|lo|la|lv|lt|lb|mk|mg|ms|ml|mt|mi|mr|mn|my|ne|no|ps|fa|pl|pt|pa|ro|ru|sm|gd|sr|st|sn|sd|si|sk|sl|so|es|su|sw|sv|tg|ta|te|th|tr|uk|ur|uz|vi|cy|xh|yi|yo|zu)/(af|sq|am|ar|hy|az|eu|be|bn|bs|bg|ca|ceb|ny|zh-CN|zh-TW|co|hr|cs|da|nl|en|eo|et|tl|fi|fr|fy|gl|ka|de|el|gu|ht|ha|haw|iw|hi|hmn|hu|is|ig|id|ga|it|ja|jw|kn|kk|km|ko|ku|ky|lo|la|lv|lt|lb|mk|mg|ms|ml|mt|mi|mr|mn|my|ne|no|ps|fa|pl|pt|pa|ro|ru|sm|gd|sr|st|sn|sd|si|sk|sl|so|es|su|sw|sv|tg|ta|te|th|tr|uk|ur|uz|vi|cy|xh|yi|yo|zu)/(.*)$ /$1/$3 permanent;
rewrite ^/(af|sq|am|ar|hy|az|eu|be|bn|bs|bg|ca|ceb|ny|zh-CN|zh-TW|co|hr|cs|da|nl|en|eo|et|tl|fi|fr|fy|gl|ka|de|el|gu|ht|ha|haw|iw|hi|hmn|hu|is|ig|id|ga|it|ja|jw|kn|kk|km|ko|ku|ky|lo|la|lv|lt|lb|mk|mg|ms|ml|mt|mi|mr|mn|my|ne|no|ps|fa|pl|pt|pa|ro|ru|sm|gd|sr|st|sn|sd|si|sk|sl|so|es|su|sw|sv|tg|ta|te|th|tr|uk|ur|uz|vi|cy|xh|yi|yo|zu)/(.*)$ /gtranslate/gtranslate.php?glang=$1&gurl=$2 last;
rewrite ^/(af|sq|am|ar|hy|az|eu|be|bn|bs|bg|ca|ceb|ny|zh-CN|zh-TW|co|hr|cs|da|nl|en|eo|et|tl|fi|fr|fy|gl|ka|de|el|gu|ht|ha|haw|iw|hi|hmn|hu|is|ig|id|ga|it|ja|jw|kn|kk|km|ko|ku|ky|lo|la|lv|lt|lb|mk|mg|ms|ml|mt|mi|mr|mn|my|ne|no|ps|fa|pl|pt|pa|ro|ru|sm|gd|sr|st|sn|sd|si|sk|sl|so|es|su|sw|sv|tg|ta|te|th|tr|uk|ur|uz|vi|cy|xh|yi|yo|zu)$ /$1/ permanent;
```

``` appache conf
# gtranslate config
RewriteRule ^(af|sq|am|ar|hy|az|eu|be|bn|bs|bg|ca|ceb|ny|zh-CN|zh-TW|co|hr|cs|da|nl|en|eo|et|tl|fi|fr|fy|gl|ka|de|el|gu|ht|ha|haw|iw|hi|hmn|hu|is|ig|id|ga|it|ja|jw|kn|kk|km|ko|ku|ky|lo|la|lv|lt|lb|mk|mg|ms|ml|mt|mi|mr|mn|my|ne|no|ps|fa|pl|pt|pa|ro|ru|sm|gd|sr|st|sn|sd|si|sk|sl|so|es|su|sw|sv|tg|ta|te|th|tr|uk|ur|uz|vi|cy|xh|yi|yo|zu)/(af|sq|am|ar|hy|az|eu|be|bn|bs|bg|ca|ceb|ny|zh-CN|zh-TW|co|hr|cs|da|nl|en|eo|et|tl|fi|fr|fy|gl|ka|de|el|gu|ht|ha|haw|iw|hi|hmn|hu|is|ig|id|ga|it|ja|jw|kn|kk|km|ko|ku|ky|lo|la|lv|lt|lb|mk|mg|ms|ml|mt|mi|mr|mn|my|ne|no|ps|fa|pl|pt|pa|ro|ru|sm|gd|sr|st|sn|sd|si|sk|sl|so|es|su|sw|sv|tg|ta|te|th|tr|uk|ur|uz|vi|cy|xh|yi|yo|zu)/(.*)$ /$1/$3 [R=301,L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(af|sq|am|ar|hy|az|eu|be|bn|bs|bg|ca|ceb|ny|zh-CN|zh-TW|co|hr|cs|da|nl|en|eo|et|tl|fi|fr|fy|gl|ka|de|el|gu|ht|ha|haw|iw|hi|hmn|hu|is|ig|id|ga|it|ja|jw|kn|kk|km|ko|ku|ky|lo|la|lv|lt|lb|mk|mg|ms|ml|mt|mi|mr|mn|my|ne|no|ps|fa|pl|pt|pa|ro|ru|sm|gd|sr|st|sn|sd|si|sk|sl|so|es|su|sw|sv|tg|ta|te|th|tr|uk|ur|uz|vi|cy|xh|yi|yo|zu)/(.*)$ /gtranslate/gtranslate.php?glang=$1&gurl=$2 [L,QSA]
RewriteRule ^(af|sq|am|ar|hy|az|eu|be|bn|bs|bg|ca|ceb|ny|zh-CN|zh-TW|co|hr|cs|da|nl|en|eo|et|tl|fi|fr|fy|gl|ka|de|el|gu|ht|ha|haw|iw|hi|hmn|hu|is|ig|id|ga|it|ja|jw|kn|kk|km|ko|ku|ky|lo|la|lv|lt|lb|mk|mg|ms|ml|mt|mi|mr|mn|my|ne|no|ps|fa|pl|pt|pa|ro|ru|sm|gd|sr|st|sn|sd|si|sk|sl|so|es|su|sw|sv|tg|ta|te|th|tr|uk|ur|uz|vi|cy|xh|yi|yo|zu)$ /$1/ [R=301,L]

```