# 📘 license_decorator.php 使用文档

> PHP 客户端许可证验证 SDK · 对标 Python 版 `license_decorator.py`

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)]()
[![PHP](https://img.shields.io/badge/PHP-7.0%2B-purple.svg)]()
[![License](https://img.shields.io/badge/license-MIT-green.svg)]()

---

## 📑 目录

- [一、SDK 简介](#一sdk-简介)
- [二、快速开始（5分钟接入）](#二快速开始5分钟接入)
- [三、安装部署](#三安装部署)
- [四、核心概念](#四核心概念)
- [五、基础用法](#五基础用法)
- [六、高级用法](#六高级用法)
- [七、权限控制](#七权限控制)
- [八、缓存机制](#八缓存机制)
- [九、CLI 命令行模式](#九cli-命令行模式)
- [十、Web 浏览器模式](#十web-浏览器模式)
- [十一、API 完整参考](#十一api-完整参考)
- [十二、实战案例](#十二实战案例)
- [十三、错误处理](#十三错误处理)
- [十四、常见问题 FAQ](#十四常见问题-faq)
- [十五、最佳实践](#十五最佳实践)

---

## 一、SDK 简介

`license_decorator.php` 是神优软件销售平台官方提供的 **PHP 客户端验证库**，让你的 PHP 软件（Web 应用、CLI 脚本、本地工具、WordPress 插件等）能够接入许可证授权体系。

### ✨ 核心特性

| 特性 | 说明 |
|------|------|
| 🔐 设备绑定 | 每张卡密只能绑定一台电脑（基于硬件指纹） |
| 💾 离线缓存 | 本地加密缓存 24 小时，无需频繁联网 |
| 💓 心跳保活 | 防止服务器长时间无响应自动踢号 |
| 🎛️ 权限分级 | VIP 等级、功能开关、使用次数多维控制 |
| 🔏 签名验证 | MD5 签名 + 时间戳防重放攻击 |
| 🌐 Web/CLI 双模 | 浏览器自动弹窗，命令行交互输入 |
| 📦 零依赖 | 仅需 PHP 7.0+ 和 cURL 扩展 |

### 🆚 与 Python 版对比

| 维度 | Python 版 | PHP 版 |
|------|---------|--------|
| 设备指纹 | MD5 + SHA256 | MD5 + SHA256（一致） |
| 缓存加密 | XOR | XOR（一致） |
| 签名算法 | MD5 + 排序 | MD5 + 排序（一致） |
| GUI 激活 | customtkinter 弹窗 | HTML 弹窗（Web） + STDIN（CLI） |
| 装饰器 | `@require_license` | `require_license()` 函数 |
| 适用场景 | Python 桌面软件 | PHP Web/CLI/插件 |

### 📦 文件清单

```
license_decorator.php         ← SDK 主文件（必需）
├── 类：PhpLicenseValidator
└── 函数：require_license()
```

---

## 二、快速开始（5分钟接入）

### 第 1 步：获取项目密钥

登录「神优后台」→ **🔧 API 项目管理** → 选择/创建项目，记下两个值：

- `project_id`：项目 ID（如 `1001`）
- `api_secret`：API 密钥（如 `f2113e6c61b86a7c61a74c3756b684fa`）

### 第 2 步：引入 SDK

把 `license_decorator.php` 放到你的项目目录（如 `/var/www/myapp/`），然后在主入口文件引入：

```php
<?php
require_once __DIR__ . '/license_decorator.php';
```

### 第 3 步：实例化并验证

```php
<?php
require_once __DIR__ . '/license_decorator.php';

$license = new PhpLicenseValidator(
    '1001',                                          // 项目 ID
    'f2113e6c61b86a7c61a74c3756b684fa',              // API 密钥
    '我的软件 v1.0',                                 // 软件名称（显示在激活窗口）
    'v1'                                             // 缓存后缀（区分多个软件）
);

if (!$license->check()) {
    $license->showActivationDialog();
    exit;
}

// 验证通过，运行你的软件
echo "✅ 已授权\n";
runMySoftware();
```

**完成！** 🎉 首次访问会自动弹出激活窗口，输入卡密即可。

---

## 三、安装部署

### 环境要求

| 项目 | 最低版本 | 推荐版本 |
|------|---------|---------|
| PHP | 7.0 | 7.4 / 8.0+ |
| cURL 扩展 | 必需 | 任意 |
| OpenSSL | 推荐 | 任意 |
| 磁盘空间 | 1 MB | — |

### 部署步骤

```bash
# 1. 上传 SDK 文件
scp license_decorator.php user@server:/var/www/myapp/

# 2. 确保 db/ 目录可写（用于缓存）
mkdir -p /var/www/myapp/db
chmod 755 /var/www/myapp/db

# 3. 验证 PHP 扩展
php -m | grep curl   # 必须有 curl
php -m | grep openssl # 推荐有 openssl
```

### 目录结构示例

```
/var/www/myapp/
├── license_decorator.php     ← SDK
├── index.php                 ← 你的主入口
├── config.php                ← 你的配置
├── db/                       ← 缓存目录（自动创建）
│   ├── license_cache_v1.bin  ← 加密缓存（自动生成）
│   └── license_cache_v1.json ← 明文缓存（自动生成）
└── ...
```

---

## 四、核心概念

### 1. 设备指纹（Device Fingerprint）

SDK 通过收集**4 层硬件信息**生成唯一设备指纹，防止一张卡密在多台电脑上使用：

```
设备指纹 = MD5(主机名 + 机器类型 + CPU + 系统 + 版本)
硬件 ID  = SHA256(主机名 + 机器类型 + CPU)[:32]
MAC 地址 = 网卡物理地址
```

### 2. 加密缓存（Local Cache）

SDK 会把激活信息**加密存储**到本地 `db/license_cache_*.bin`：

- 加密算法：XOR（数据字节 ^ 密钥字节循环）
- 密钥：`SHA256(api_secret + device_fingerprint + hardware_id)`
- 缓存有效期：**24 小时**
- 24 小时后下次启动自动重新在线验证

### 3. API 签名（Signature）

每次 API 请求都会带签名：

```
签名算法：
1. 参数按 key 升序排序
2. 拼成字符串 "k1=v1&k2=v2&...&key=API密钥"
3. MD5(上面这串) = signature

服务端用同样算法验证签名匹配，且 time stamp 5 分钟内有效
```

### 4. 工作流程

```
┌─────────── 客户电脑 ──────────┐         ┌─── 神优服务器 ───┐
│                              │         │                  │
│ 1. 启动软件                  │         │                  │
│    ↓                         │         │                  │
│ 2. 读本地缓存                 │         │                  │
│    ├─ 有效（<24h）           │         │                  │
│    │  → 直接运行 ✅          │         │                  │
│    └─ 无效/过期               │         │                  │
│       ↓                      │         │                  │
│ 3. 弹激活窗口                  │         │                  │
│    ↓                         │         │                  │
│ 4. 用户输入卡密               │         │                  │
│    ↓                         │         │                  │
│ 5. 收集设备指纹 ───────────► HTTPS ──►│ 验证签名           │
│    ↓                         │         │ 校验状态           │
│ 6. 收到响应                   │         │ 写入数据库         │
│    ↓                         │ ◄──────│ 返回结果           │
│ 7. 保存加密缓存                │         │                  │
│    ↓                         │         │                  │
│ 8. 运行软件 ✅                │         │                  │
└──────────────────────────────┘         └──────────────────┘
```

---

## 五、基础用法

### 5.1 最小化集成（推荐）

```php
<?php
require_once 'license_decorator.php';

// 一行代码搞定（自动检测激活 + 弹激活窗口）
$license = require_license(
    '1001',                          // 项目 ID
    'f2113e6c61b86a7c61a74c3756b684fa', // API 密钥
    '我的软件',                       // 软件名
    'v1'                             // 缓存后缀
);

// 已激活，使用 $license
echo "✅ 已激活（剩 " . $license->getLicenseInfo()['remaining_days'] . " 天）";
```

### 5.2 手动控制流程

```php
<?php
require_once 'license_decorator.php';

$license = new PhpLicenseValidator(
    '1001',
    'f2113e6c61b86a7c61a74c3756b684fa',
    '我的软件',
    'v1'
);

// 步骤 1：尝试加载本地缓存
if ($license->loadCache()) {
    echo "✅ 本地缓存有效\n";
    $info = $license->getLicenseInfo();
} else {
    // 步骤 2：缓存无效 → 弹激活窗口
    $license->showActivationDialog();
    // 用户激活后页面会自动刷新，重新进入这里
    exit;
}

// 步骤 3：执行业务逻辑
echo "许可证：" . $info['license_name'] . "\n";
echo "剩余天数：" . $info['remaining_days'] . "\n";
```

### 5.3 自定义 API 地址

如果你的服务端不是默认地址：

```php
$license = new PhpLicenseValidator(
    '1001',
    'f2113e6c61b86a7c61a3756b684fa',
    '我的软件',
    'v1',
    'https://api.your-domain.com/api.php'  // 第 5 个参数：自定义 API 地址
);
```

---

## 六、高级用法

### 6.1 检查某个卡密（不激活）

```php
$result = $license->checkLicense('DAY-A5F3B9D2C1E7F4G6');
print_r($result);

/* 输出示例：
Array (
    [status] => success
    [code] => SUCCESS
    [message] => 许可证有效
    [data] => Array (
        [license_key] => DAY-A5F3B9D2C1E7F4G6
        [license_type] => 年卡
        [status] => active
        [duration_days] => 365
    )
)
*/
```

### 6.2 续期卡密（换新卡密）

```php
$result = $license->renewLicense('OLD-1234-5678', 'NEW-ABCD-EFGH');
if ($result['status'] === 'success') {
    echo "✅ 续期成功\n";
}
```

### 6.3 解绑当前设备（换电脑用）

```php
$result = $license->deactivateLicense();
if ($result['status'] === 'success') {
    echo "✅ 已解绑当前设备\n";
    // 清理本地缓存
    $license->clearCache();
}
```

### 6.4 心跳保活（防被踢下线）

适合长时间运行的程序（如后台守护进程、SaaS 服务）：

```php
// 每 5 分钟调用一次
while (true) {
    doWork();
    
    $result = $license->heartbeat();
    if ($result['status'] !== 'success') {
        // 心跳失败，可能被踢下线
        log("心跳失败：" . $result['message']);
        // 可选：强制重新激活
    }
    
    sleep(300); // 5 分钟
}
```

### 6.5 强制在线验证（忽略缓存）

```php
// 不管缓存是否有效，都强制调用一次在线验证
$result = $license->validateLicenseOnline();
if ($result['status'] === 'success') {
    echo "✅ 在线验证通过\n";
}
```

### 6.6 获取设备信息

```php
// 设备指纹（32 位 MD5）
echo $license->getDeviceFingerprint();

// 完整设备信息
$device = $license->getDeviceInfo();
print_r($device);
/*
Array (
    [device_fingerprint] => a1b2c3d4e5f6...
    [mac_address] => 00:11:22:33:44:55
    [hardware_id] => 9f8e7d6c5b4a...
)
*/
```

---

## 七、权限控制

SDK 支持「按功能」和「按数量」两种权限控制方式。

### 7.1 功能权限（布尔型）

| 方法 | 功能名称 | 默认 |
|------|---------|------|
| `checkFeature('export_excel')` | 导出 Excel | 关闭=无权限 |
| `checkFeature('batch_import')` | 批量导入 | 关闭=无权限 |
| `checkFeature('advanced_analytics')` | 高级分析 | 关闭=无权限 |
| `checkFeature('api_access')` | API 访问 | 关闭=无权限 |
| `checkFeature('custom_template')` | 自定义模板 | 关闭=无权限 |

**示例：**

```php
// 根据权限启用/禁用导出功能
if ($license->checkFeature('export_excel')) {
    // 显示导出按钮
    echo '<button>导出</button>';
} else {
    // 隐藏/显示升级提示
    echo '<div class="upgrade-tip">导出功能需要升级许可证</div>';
}

// 或在按钮点击时检查
function onExportClick() {
    if (!$license->checkFeature('export_excel')) {
        alert("您的许可证不支持导出功能");
        return;
    }
    doExport();
}
```

### 7.2 数量限制（数值型）

| 方法 | 默认值 | 说明 |
|------|--------|------|
| `getMaxProjects()` | 999 | 最大项目数 |
| `getMaxServers()` | 999 | 最大服务器数 |
| `getLimit('daily_queries')` | 99999 | 每日查询次数 |
| `getLimit('concurrent_users')` | 99 | 最大并发用户 |

**示例：**

```php
// 限制用户最多创建 N 个项目
$maxProjects = $license->getMaxProjects();
$currentCount = getCurrentProjectCount();

if ($currentCount >= $maxProjects) {
    die("❌ 已达项目数上限 ($currentCount/$maxProjects)，请升级许可证");
}

// 限制每日查询次数
$dailyLimit = $license->getLimit('daily_queries', 99999);
$todayUsed = getTodayUsageCount();

if ($todayUsed >= $dailyLimit) {
    die("❌ 今日查询次数已达上限 ($todayUsed/$dailyLimit)");
}
```

### 7.3 VIP 等级判断

```php
$info = $license->getLicenseInfo();

if ($info['is_vip']) {
    echo "🎖️ VIP 用户\n";
    echo "   等级：" . $info['vip_info']['level'] . "\n";
    echo "   到期：" . $info['vip_info']['expiry'] . "\n";
    
    // 启用 VIP 专属功能
    enableVipFeatures();
}
```

### 7.4 一次性获取所有权限

```php
$perms = $license->getRequiredPermissions();
print_r($perms);
/*
Array (
    [max_projects] => 1
    [max_servers] => 999
    [features] => Array (
        [export_excel] => 1
        [batch_import] => 1
        [api_access] => 
        ...
    )
    [limits] => Array (
        [daily_queries] => 100
        [concurrent_users] => 5
    )
)
*/
```

---

## 八、缓存机制

### 8.1 工作原理

```
┌─────────────────────────────────┐
│  软件启动                       │
│         ↓                       │
│  loadCache() 调用                │
│         ↓                       │
│  ┌─────────────────────┐        │
│  │ 检查 db/license_cache_*.bin │ │
│  └─────────────────────┘        │
│         ↓                       │
│  ├─ 文件不存在 → 返回 false      │
│  ├─ 文件存在但已过期 → 清理返回 false │
│  ├─ 文件存在且在 24h 内 → 解密  │
│  │   ├─ 解密成功 → 用缓存       │
│  │   └─ 解密失败 → 清理返回 false │
│  └─ 文件存在但超 24h → 在线验证 │
└──────────────────────────────────┘
```

### 8.2 缓存方法

| 方法 | 说明 |
|------|------|
| `loadCache($forceOnlineCheck = false)` | 加载本地缓存，自动判断是否需要在线验证 |
| `saveCache()` | 保存当前激活状态到本地（一般自动调用） |
| `clearCache()` | 清除本地缓存 |

### 8.3 自定义缓存目录

默认缓存目录是 `db/`。如需修改：

```php
// 通过反射修改（高级用法）
$reflection = new ReflectionClass($license);
$prop = $reflection->getProperty('cacheDir');
$prop->setAccessible(true);
$prop->setValue($license, '/var/lib/myapp/cache');
```

> 注：标准做法是确保 `db/` 目录可写，不要修改默认目录。

### 8.4 多产品共享缓存

使用 `cacheSuffix` 参数区分不同产品：

```php
$app1 = new License("...", "...", "产品 A", "product_a_v1");
$app2 = new License("...", "...", "产品 B", "product_b_v1");
```

这样会生成两个独立的缓存文件，互不干扰：

```
db/
├── license_cache_product_a_v1.bin
├── license_cache_product_a_v1.json
├── license_cache_product_b_v1.bin
└── license_cache_product_b_v1.json
```

---

## 九、CLI 命令行模式

CLI 模式下，`showActivationDialog()` 会自动切换为**交互式输入**：

### 9.1 简单用法

```php
#!/usr/bin/env php
<?php
require_once 'license_decorator.php';

$license = new PhpLicenseValidator('1001', 'f2...', 'CLI 工具', 'cli_v1');

if (!$license->check()) {
    // 自动在终端让用户输入
    $license->showActivationDialog();
    exit(1);
}

echo "✅ 已激活，开始处理...\n";
processData();
```

运行效果：

```
=== CLI 工具 - 激活软件 ===
设备指纹: a1b2c3d4e5f6g7h8...
硬件 ID:  9f8e7d6c5b4a3z2y...

请输入您的卡密: DAY-A5F3B9D2C1E7F4G6
✅ 激活成功！
```

### 9.2 Cron 定时任务用法

```php
#!/usr/bin/env php
<?php
// /usr/local/bin/my-cron.php
require_once '/var/www/myapp/license_decorator.php';

$license = new PhpLicenseValidator(
    '1001',
    'f2113e6c61b86a7c61a74c3756b684fa',
    '定时任务',
    'cron_v1'
);

if (!$license->check()) {
    // 写入日志而不是交互（cron 不支持 stdin）
    file_put_contents(
        '/var/log/myapp-error.log',
        date('Y-m-d H:i:s') . " 软件未激活，跳过执行\n",
        FILE_APPEND
    );
    exit(1);
}

processScheduledTasks();
echo "✅ 任务完成\n";
```

### 9.3 非交互模式（无人值守激活）

通过环境变量传入卡密：

```bash
# 第一次激活（命令行传入卡密）
LICENSE_KEY="DAY-A5F3B9D2C1E7F4G6" php activate.php

# activate.php 内容
$licenseCode = getenv('LICENSE_KEY');
if (!$licenseCode) {
    fwrite(STDERR, "请设置环境变量 LICENSE_KEY\n");
    exit(1);
}
$result = $license->activateLicense($licenseCode);
if ($result['status'] === 'success') {
    echo "✅ 激活成功\n";
}
```

---

## 十、Web 浏览器模式

Web 模式下，`showActivationDialog()` 会自动渲染一个**蓝色调激活弹窗**（HTML），用户填写卡密提交后会通过 JavaScript 异步调用激活 API。

### 10.1 自动弹窗模式（推荐）

```php
<?php
require_once 'license_decorator.php';

// 自动检测：未激活 → 弹窗，已激活 → 继续
$license = require_license('1001', 'f2...', '我的软件', 'v1');

// 已激活，执行业务逻辑
doMyWork();
```

### 10.2 自定义弹窗样式

如需自定义样式，可以直接在 PHP 中输出你的 HTML，然后调用 `activateLicense()`：

```php
<?php
if (!$license->check()) {
    ?>
    <!DOCTYPE html>
    <html>
    <head>
        <title>激活 - 我的软件</title>
        <style>
            /* 你的自定义样式 */
        </style>
    </head>
    <body>
        <form method="POST" action="?action=activate">
            <h1>请输入卡密</h1>
            <input type="text" name="license" placeholder="卡密">
            <button type="submit">激活</button>
        </form>
    </body>
    </html>
    <?php
    exit;
}

// 处理提交
if ($_GET['action'] === 'activate' && $_POST['license']) {
    $result = $license->activateLicense($_POST['license']);
    if ($result['status'] === 'success') {
        // 跳转或刷新
        header('Location: index.php');
    } else {
        echo "激活失败：" . $result['message'];
    }
}
```

### 10.3 AJAX 异步激活

适合 SPA（单页应用）：

```php
<?php
// api_activate.php
require_once 'license_decorator.php';

header('Content-Type: application/json');

$licenseCode = $_POST['license'] ?? '';
if (!$licenseCode) {
    echo json_encode(['success' => false, 'message' => '卡密不能为空']);
    exit;
}

$license = new PhpLicenseValidator('1001', 'f2...', '软件', 'v1');
$result = $license->activateLicense($licenseCode);

echo json_encode([
    'success' => $result['status'] === 'success',
    'message' => $result['message'] ?? '未知错误',
    'data' => $result['data'] ?? null,
]);
```

前端 JavaScript 调用：

```javascript
async function activate(licenseCode) {
    const resp = await fetch('api_activate.php', {
        method: 'POST',
        headers: {'Content-Type': 'application/x-www-form-urlencoded'},
        body: 'license=' + encodeURIComponent(licenseCode)
    });
    const data = await resp.json();
    if (data.success) {
        alert('激活成功！');
        location.reload();
    } else {
        alert('激活失败：' + data.message);
    }
}
```

---

## 十一、API 完整参考

### 11.1 构造函数

```php
PhpLicenseValidator(
    string $projectId,          // 必填：项目 ID
    string $projectApiSecret,   // 必填：API 密钥
    string $appName = '软件名称', // 选填：软件名称
    string $cacheSuffix = '',    // 选填：缓存后缀
    string $apiBase = 'http://apk.com/api.php' // 选填：API 地址
)
```

### 11.2 核心方法

| 方法 | 返回值 | 说明 |
|------|--------|------|
| `check()` | `bool` | 一键检查（自动用缓存或在线） |
| `loadCache($forceOnline)` | `bool` | 加载本地缓存 |
| `saveCache()` | `bool` | 保存到本地缓存 |
| `clearCache()` | `bool` | 清除本地缓存 |
| `activateLicense($code)` | `array` | 激活卡密 |
| `validateLicenseOnline($code)` | `array` | 在线验证 |
| `checkLicense($code)` | `array` | 检查卡密（不绑定） |
| `deactivateLicense($code)` | `array` | 解绑设备 |
| `renewLicense($old, $new)` | `array` | 续期卡密 |
| `heartbeat($code)` | `array` | 心跳保活 |
| `showActivationDialog()` | `void` | 弹激活窗口（Web/CLI） |
| `getLicenseInfo()` | `array|null` | 获取当前许可证详情 |
| `getDeviceFingerprint()` | `string` | 获取设备指纹 |
| `getDeviceInfo()` | `array` | 获取完整设备信息 |

### 11.3 权限方法

| 方法 | 返回值 | 说明 |
|------|--------|------|
| `checkFeature($name)` | `bool` | 检查功能权限 |
| `getLimit($name, $default)` | `int\|null` | 获取数量限制 |
| `getMaxProjects()` | `int` | 最大项目数 |
| `getMaxServers()` | `int` | 最大服务器数 |
| `getRequiredPermissions()` | `array` | 完整权限配置 |

### 11.4 全局函数

```php
require_license(
    string $projectId,
    string $projectApiSecret,
    string $appName = '软件名称',
    string $cacheSuffix = ''
): PhpLicenseValidator
```

**返回**：已激活的 `PhpLicenseValidator` 实例（未激活会先弹窗）

---

## 十二、实战案例

### 12.1 WordPress 插件授权

```php
<?php
// 在插件主文件 my-plugin.php
require_once plugin_dir_path(__FILE__) . 'sdk/license_decorator.php';

$license = new PhpLicenseValidator(
    '1001',
    'f2113e6c61b86a7c61a74c3756b684fa',
    '我的 WordPress 插件',
    'wp_v1'
);

if (!$license->check()) {
    add_action('admin_notices', function() {
        echo '<div class="notice notice-error">请先激活插件</div>';
    });
    return; // 不加载插件功能
}

// 已激活，加载插件功能
require_once plugin_dir_path(__FILE__) . 'includes/main.php';
```

### 12.2 数据导出工具（带权限）

```php
<?php
require_once 'license_decorator.php';

$license = require_license('1001', 'f2...', '数据导出工具', 'export_v1');

if (!$license->checkFeature('export_excel')) {
    http_response_code(403);
    die('<h1>403 权限不足</h1><p>您的套餐未包含此功能</p>');
}

header('Content-Type: application/vnd.ms-excel');
header('Content-Disposition: attachment; filename="data.xls"');

echo "ID\t名称\t价格\n";
foreach (getData() as $row) {
    echo "{$row['id']}\t{$row['name']}\t{$row['price']}\n";
}
```

### 12.3 带使用次数统计

```php
<?php
require_once 'license_decorator.php';

$license = require_license('1001', 'f2...', '查询工具', 'query_v1');

// 检查每日查询次数
$dailyLimit = $license->getLimit('daily_queries', 100);

$counterFile = 'db/usage_count_' . date('Ymd') . '.txt';
$used = (int)(file_exists($counterFile) ? file_get_contents($counterFile) : 0);

if ($used >= $dailyLimit) {
    die("❌ 今日查询次数已达上限 ($used/$dailyLimit)");
}

// 执行查询
$result = doQuery($_GET['keyword'] ?? '');

// 增加计数
file_put_contents($counterFile, $used + 1);

echo "✅ 查询成功（今日 $used/$dailyLimit）\n";
print_r($result);
```

### 12.4 后台守护进程

```php
#!/usr/bin/env php
<?php
require_once 'license_decorator.php';

$license = new PhpLicenseValidator('1001', 'f2...', '守护进程', 'daemon_v1');

// 启动时检查
if (!$license->check()) {
    $license->showActivationDialog(); // CLI 模式
    exit(1);
}

// 主循环
$lastHeartbeat = 0;
while (true) {
    // 每 5 分钟心跳一次
    if (time() - $lastHeartbeat >= 300) {
        $result = $license->heartbeat();
        if ($result['status'] !== 'success') {
            log("心跳失败：" . $result['message']);
        }
        $lastHeartbeat = time();
    }
    
    // 执行业务
    doWork();
    
    sleep(10);
}
```

### 12.5 API 转发服务

把神优 API 包装成你自己的 API：

```php
<?php
// my_api.php
require_once 'license_decorator.php';

header('Content-Type: application/json');

$license = new PhpLicenseValidator('1001', 'f2...', 'API 服务', 'api_v1');
$action = $_GET['action'] ?? '';
$code = $_GET['license'] ?? '';

switch ($action) {
    case 'check':
        $result = $license->checkLicense($code);
        break;
    case 'activate':
        $result = $license->activateLicense($code);
        break;
    // ... 其他 action
    default:
        $result = ['status' => 'error', 'message' => '未知操作'];
}

echo json_encode($result);
```

---

## 十三、错误处理

### 13.1 错误码对照表

| 错误码 | 含义 | 处理建议 |
|--------|------|---------|
| `SUCCESS` | 成功 | — |
| `INVALID_PARAMS` | 参数错误 | 检查必填字段 |
| `INVALID_SIGNATURE` | 签名失败 | 检查 API 密钥 |
| `TIMESTAMP_EXPIRED` | 时间戳过期 | 同步服务器时间 |
| `PROJECT_NOT_FOUND` | 项目不存在 | 检查 project_id |
| `LICENSE_NOT_FOUND` | 卡密不存在 | 检查卡密输入 |
| `LICENSE_EXPIRED` | 卡密已过期 | 提示用户续费 |
| `LICENSE_USED` | 卡密已被使用 | 提示用户解绑或换设备 |
| `LICENSE_DISABLED` | 卡密已禁用 | 联系客服 |
| `DEVICE_MISMATCH` | 设备不匹配 | 提示用户解绑原设备 |
| `KICKOFF_COOLDOWN` | 顶号冷却中 | 等待 60 秒后重试 |
| `RATE_LIMIT` | 请求频率过高 | 降低调用频率 |
| `DATABASE_ERROR` | 数据库错误 | 联系技术支持 |
| `INTERNAL_ERROR` | 服务器异常 | 联系技术支持 |

### 13.2 统一错误处理模式

```php
$result = $license->activateLicense($code);

if ($result['status'] === 'success') {
    // 成功逻辑
} else {
    $code = $result['code'] ?? 'UNKNOWN';
    $message = $result['message'] ?? '未知错误';
    
    switch ($code) {
        case 'LICENSE_EXPIRED':
            showMessage("您的卡密已过期，请续费");
            break;
        case 'DEVICE_MISMATCH':
            showMessage("卡密已绑定其他设备，请先解绑");
            break;
        case 'RATE_LIMIT':
            showMessage("请求过于频繁，请稍后再试");
            break;
        default:
            showMessage("错误 [$code]：$message");
    }
}
```

---

## 十四、常见问题 FAQ

### ❓ Q1: 激活后多久需要联网一次？

**A**: 本地缓存默认 24 小时。超过 24 小时后下次启动会自动在线验证。

如果你的程序需要长时间不间断运行（如守护进程），建议每 5-10 分钟主动调用一次 `heartbeat()`。

### ❓ Q2: 客户换电脑了怎么办？

**A**: 三种方法：
1. 让客户在软件内执行 `deactivateLicense()` 解绑当前设备
2. 客户在神优后台手动「解绑设备」
3. 联系客服处理

### ❓ Q3: API 服务器挂了怎么办？

**A**: SDK 会自动 fallback 到本地缓存。如果缓存也在 24 小时内，则继续放行（用户体验更好）；都失效则拒绝服务。

### ❓ Q4: 客户修改 SDK 文件绕过验证怎么办？

**A**: SDK 是明文的，技术上确实可以绕过。建议：
1. 关键业务逻辑用 [Swoole Compiler](https://www.swoole.com/swoole-cl) 加密
2. 关键功能增加服务端验证
3. 定期审计可疑许可证

### ❓ Q5: 签名失败（INVALID_SIGNATURE）怎么办？

**A**: 常见原因：
- 系统时间不准 → `ntpdate` 同步时间
- API 密钥错误 → 重新从后台复制
- PHP 时区设置错误 → `date_default_timezone_set('Asia/Shanghai')`

### ❓ Q6: 如何更新到最新版 SDK？

**A**: 直接下载最新版 `license_decorator.php` 覆盖即可，向后兼容。

### ❓ Q7: 能在同一个 PHP 进程里验证多个项目吗？

**A**: 可以！创建多个 `PhpLicenseValidator` 实例即可：

```php
$licA = new PhpLicenseValidator('1001', 'secret_a', '产品 A', 'a_v1');
$licB = new PhpLicenseValidator('1002', 'secret_b', '产品 B', 'b_v1');

if ($licA->check() && $licB->check()) {
    // 两个都激活了
}
```

### ❓ Q8: 缓存文件被删了会怎样？

**A**: SDK 检测不到缓存会返回 `false`，下次访问会重新弹激活窗口。**不影响**用户的实际授权状态（服务器端仍有记录）。

### ❓ Q9: 能在不同项目间共享缓存吗？

**A**: 不建议。不同项目用不同 `cacheSuffix` 区分，避免冲突。

### ❓ Q10: 卡密能在多个 PHP 网站上共用吗？

**A**: 不能。一张卡密绑定一台设备。如果需要多台设备共用，需要购买多张卡密或在后台为该用户设置多设备许可。

---

## 十五、最佳实践

### ✅ DO（推荐做法）

1. **始终使用 `require_license()` 一行接入**：
   ```php
   $license = require_license('1001', 'f2...', '软件名');
   ```

2. **业务代码加密后再部署**：
   ```bash
   ./swoole-compiler encrypt --input my_app.php --output my_app.compiled.php
   ```

3. **关键功能双重验证**：
   ```php
   // 关键操作都调用 API 验证一次
   $license->heartbeat();
   ```

4. **使用有意义的 cacheSuffix**：
   ```php
   $cacheSuffix = 'myapp_v2_enterprise';  // 不要用随机数
   ```

5. **处理好错误**：
   ```php
   if ($result['status'] !== 'success') {
       // 显示友好提示，不要直接 echo var_dump
   }
   ```

### ❌ DON'T（不要做的事）

1. **不要硬编码卡密**：永远不要在代码里写死卡密，应该让用户输入。

2. **不要在 SDK 中绕过激活**：
   ```php
   // ❌ 错误
   if (true) { // 注释掉 check()
       runMySoftware();
   }
   ```

3. **不要把 SDK 加密**：SDK 必须明文，否则 PHP 无法解析。

4. **不要把 API 密钥写在客户端代码里**：
   ```php
   // ❌ 危险：密钥泄露
   $license = new PhpLicenseValidator('1001', 'f2113e6c61b86a7c61a74c3756b684fa', ...);
   ```

   > 注：API 密钥必须配合设备指纹使用，单凭密钥无法在其他设备激活。但如果客户从源代码读到密钥，可以伪造请求。建议：
   > - 业务代码用 Swoole Compiler 加密
   > - 关键操作加入服务端验证

5. **不要无限缓存**：定期在线验证避免服务器端异常时本地永久通过。

6. **不要忽略 heartbeat**：长时间运行的程序必须定期心跳。

---

## 📞 技术支持

- 📖 **完整文档站**：访问 `SDK_php_guide.php`
- 🐛 **问题反馈**：联系神优后台客服
- 💬 **QQ 群**：123456789
- 📧 **邮件**：support@apk.com

---

## 📜 版本历史

### v1.0.0 (2026-10-03)

- ✅ 首版本发布
- ✅ 支持 Web / CLI 双模式
- ✅ 设备指纹 + 离线缓存 + 心跳保活
- ✅ 7 个 API 动作（check/validate/activate/deactivate/renew/heartbeat）
- ✅ 完整权限控制（功能开关 + 数量限制）
- ✅ 一行接入函数 `require_license()`

---

## 📄 License

MIT License

```
MIT License

Copyright (c) 2026 神优软件销售平台

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...
```

---

**🎉 开始为你的 PHP 软件加上专业级加密保护吧！**