核心函数

Yuan-ICP 系统的核心函数库位于 includes/functions.php 文件中，提供了系统运行所需的各种基础功能和工具函数。

📋 函数概览

核心函数库包含以下主要类别：

数据库操作：数据库连接和查询相关函数
安全功能：密码加密、CSRF防护等安全函数
邮件系统：邮件发送和模板处理
业务逻辑：备案号生成、靓号判断等业务函数
工具函数：通用工具和辅助函数

🗄️ 数据库操作函数

`db($reset = false)`

获取数据库连接实例

参数：

$reset (bool): 是否重置连接，默认为 false

返回值：PDO 数据库连接对象

功能：

支持 MySQL、PostgreSQL、SQLite 多种数据库
使用单例模式，避免重复连接
自动配置错误模式和获取模式
支持测试环境的预配置连接

使用示例：

php

// 获取数据库连接
$db = db();

// 执行查询
$stmt = $db->prepare("SELECT * FROM icp_applications WHERE id = ?");
$stmt->execute([1]);
$result = $stmt->fetch();

// 强制重新连接
$db = db(true);

`db_now()`

获取当前数据库兼容的时间戳函数

返回值：适合当前数据库的时间函数字符串

功能：

SQLite: 返回 datetime('now')
MySQL: 返回 NOW()
PostgreSQL: 返回 NOW()

使用示例：

php

// 插入当前时间
$db = db();
$stmt = $db->prepare("INSERT INTO announcements (title, content, created_at) VALUES (?, ?, " . db_now() . ")");
$stmt->execute(['标题', '内容']);

`config($key, $default = null)`

加载配置文件

参数：

$key (string): 配置文件名（不含.php扩展名）
$default (mixed): 默认值，文件不存在时返回

返回值：配置数组或默认值

功能：

缓存机制，避免重复读取
文件大小限制（最大100KB）
格式验证，确保返回数组
异常处理，提供详细错误信息

使用示例：

php

// 加载数据库配置
$dbConfig = config('database');

// 加载配置，提供默认值
$appConfig = config('app', ['debug' => false]);

🔐 安全功能函数

`hash_password($password)`

密码哈希加密

参数：

$password (string): 明文密码

返回值：加密后的密码哈希

功能：

使用 PHP 内置的 password_hash() 函数
采用 PASSWORD_DEFAULT 算法
自动生成盐值

使用示例：

php

// 加密用户密码
$hashedPassword = hash_password('user123456');

// 存储到数据库
$db = db();
$stmt = $db->prepare("INSERT INTO admin_users (username, password) VALUES (?, ?)");
$stmt->execute(['admin', $hashedPassword]);

`verify_password($password, $hash)`

密码验证

参数：

$password (string): 明文密码
$hash (string): 存储的密码哈希

返回值：bool，验证成功返回 true

使用示例：

php

// 用户登录验证
$inputPassword = $_POST['password'];
$storedHash = $user['password']; // 从数据库获取

if (verify_password($inputPassword, $storedHash)) {
    // 登录成功
    echo "登录成功";
} else {
    // 登录失败
    echo "密码错误";
}

`generate_csrf_token()`

生成 CSRF 令牌

返回值：32字节的十六进制 CSRF 令牌

功能：

使用 random_bytes() 生成随机令牌
自动存储到 SESSION 中
避免重复生成

使用示例：

php

// 在表单中添加 CSRF 令牌
$csrfToken = generate_csrf_token();
echo '<input type="hidden" name="csrf_token" value="' . $csrfToken . '">';

`validate_csrf_token($token)`

验证 CSRF 令牌

参数：

$token (string): 待验证的令牌

返回值：bool，验证成功返回 true

功能：

使用 hash_equals() 进行安全比较
防止时序攻击

使用示例：

php

// 验证表单提交的 CSRF 令牌
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $token = $_POST['csrf_token'] ?? '';
    if (!validate_csrf_token($token)) {
        die('CSRF 验证失败');
    }
    // 处理表单数据
}

📧 邮件系统函数

`send_email($toEmail, $toName, $subject, $body)`

发送邮件通知

参数：

$toEmail (string): 收件人邮箱
$toName (string): 收件人姓名
$subject (string): 邮件主题
$body (string): 邮件内容（HTML格式）

返回值：bool，发送成功返回 true

功能：

使用 PHPMailer 库发送邮件
自动从数据库读取 SMTP 配置
支持 HTML 和纯文本内容
详细的错误日志记录

使用示例：

php

// 发送审核通过通知
$success = send_email(
    'user@example.com',
    '张三',
    '备案申请审核通过',
    '<p>恭喜您，备案申请已通过审核！</p>'
);

if ($success) {
    echo "邮件发送成功";
} else {
    echo "邮件发送失败";
}

🎯 业务逻辑函数

`generate_unique_icp_number()`

生成唯一的备案号码

返回值：string|null，成功返回唯一号码，失败返回 null

功能：

根据系统配置的格式规则生成号码
支持自定义生成格式（{N}=数字, {U}=大写字母, {L}=小写字母）
检查保留号码列表，避免生成保留号码
确保生成的号码在数据库中唯一
最大尝试100次，避免无限循环

使用示例：

php

// 生成新的备案号
$number = generate_unique_icp_number();

if ($number) {
    echo "生成的备案号：" . $number;
    // 将号码分配给用户
} else {
    echo "号码生成失败，请稍后重试";
}

`is_premium_number($number)`

判断号码是否为靓号（自动生成模式）

参数：

$number (string): 待检查的号码

返回值：bool，是靓号返回 true

功能：

连续相同字符检测（3个或以上）
特殊吉利组合识别（666, 888, 999, 520, 1314等）
对称号码识别（AABB, ABAB模式）

使用示例：

php

// 检查号码是否为靓号
$numbers = ['Yuan888888', 'YuanABC123', 'Yuan520520'];

foreach ($numbers as $number) {
    if (is_premium_number($number)) {
        echo $number . " 是靓号\n";
    } else {
        echo $number . " 是普通号码\n";
    }
}

`check_if_number_is_premium($number)`

动态判断号码是否为靓号（兼容双模式）

参数：

$number (string): 待检查的号码

返回值：bool，是靓号返回 true

功能：

自动检测系统模式（自动生成 vs 号码池）
自动生成模式：使用规则判断
号码池模式：查询数据库标识
配置缓存机制，提高性能

使用示例：

php

// 在申请列表中显示靓号标识
$applications = $db->query("SELECT * FROM icp_applications")->fetchAll();

foreach ($applications as $app) {
    echo $app['number'];
    if (check_if_number_is_premium($app['number'])) {
        echo " <span class='badge'>靓号</span>";
    }
    echo "\n";
}

🛠️ 工具函数

`redirect($url, $statusCode = 302)`

页面重定向

参数：

$url (string): 目标URL
$statusCode (int): HTTP状态码，默认302

功能：

发送HTTP重定向头
立即终止脚本执行

使用示例：

php

// 登录成功后重定向
if ($loginSuccess) {
    redirect('/admin/dashboard.php');
}

// 永久重定向
redirect('https://new-domain.com', 301);

`current_url()`

获取当前页面URL

返回值：string，完整的当前页面URL

功能：

自动检测协议（HTTP/HTTPS）
包含主机名和请求URI

使用示例：

php

// 获取当前URL用于重定向
$currentUrl = current_url();
echo "当前页面：" . $currentUrl;

// 用于表单提交后重定向回当前页面
redirect(current_url());

`sanitizeInput($input)`

清理用户输入

参数：

$input (string): 待清理的输入

返回值：string，清理后的安全输入

注意：当前实现为临时版本，实际项目中应该实现完整的输入过滤

`isValidDomain($domain)`

验证域名格式

参数：

$domain (string): 待验证的域名

返回值：bool，格式正确返回 true

功能：

使用正则表达式验证域名格式
支持子域名和国际化域名

使用示例：

php

// 验证用户输入的域名
$domain = $_POST['domain'];

if (isValidDomain($domain)) {
    echo "域名格式正确";
} else {
    echo "请输入正确的域名格式";
}

`modify_url($new_params)`

修改URL参数

参数：

$new_params (array): 要修改的参数数组

返回值：string，修改后的查询字符串

功能：

保留现有GET参数
添加或修改指定参数
用于分页链接生成

使用示例：

php

// 生成分页链接
// 当前URL: /admin/applications.php?status=pending&page=1
$nextPageUrl = modify_url(['page' => 2]);
// 结果: ?status=pending&page=2

echo '<a href="' . $nextPageUrl . '">下一页</a>';

🔧 系统工具函数

`is_installed()`

检查系统是否已安装

返回值：bool，已安装返回 true

功能：

检查数据库连接
验证管理员用户表是否存在
异常处理，连接失败返回 false

`log_memory_usage($message)`

记录内存使用情况

参数：

$message (string): 日志消息

功能：

记录当前内存使用量
记录峰值内存使用量
用于性能调试和优化

📊 性能优化函数

内存管理

php

// 设置内存限制
ini_set('memory_limit', '1024M');

// 启用垃圾回收
gc_enable();

// 输出压缩
ini_set('zlib.output_compression', 'On');

安全配置

php

// 禁用危险函数
ini_set('disable_functions', 'exec,passthru,shell_exec,system,proc_open,popen');

// 设置正则表达式限制
ini_set('pcre.backtrack_limit', '10000');
ini_set('pcre.recursion_limit', '10000');

🚨 错误处理

异常处理原则

数据库操作使用 try-catch 捕获异常
配置文件读取提供详细错误信息
邮件发送失败记录详细日志
关键操作提供回滚机制

日志记录

php

// 错误日志配置
error_reporting(E_ALL);
ini_set('display_errors', '1');
ini_set('log_errors', '1');
ini_set('error_log', __DIR__.'/data/error.log');

💡 使用建议

最佳实践

数据库操作：使用预处理语句防止SQL注入
密码处理：始终使用哈希函数存储密码
CSRF防护：

核心函数 ​

📋 函数概览 ​

🗄️ 数据库操作函数 ​

db($reset = false) ​

db_now() ​

config($key, $default = null) ​

🔐 安全功能函数 ​

hash_password($password) ​

verify_password($password, $hash) ​

generate_csrf_token() ​

validate_csrf_token($token) ​

📧 邮件系统函数 ​

send_email($toEmail, $toName, $subject, $body) ​

🎯 业务逻辑函数 ​

generate_unique_icp_number() ​

is_premium_number($number) ​

check_if_number_is_premium($number) ​

🛠️ 工具函数 ​

redirect($url, $statusCode = 302) ​

current_url() ​

sanitizeInput($input) ​

isValidDomain($domain) ​

modify_url($new_params) ​

🔧 系统工具函数 ​

is_installed() ​

log_memory_usage($message) ​

📊 性能优化函数 ​

内存管理 ​

安全配置 ​

🚨 错误处理 ​

异常处理原则 ​

日志记录 ​

💡 使用建议 ​

最佳实践 ​

核心函数

📋 函数概览

🗄️ 数据库操作函数

`db($reset = false)`

`db_now()`

`config($key, $default = null)`

🔐 安全功能函数

`hash_password($password)`

`verify_password($password, $hash)`

`generate_csrf_token()`

`validate_csrf_token($token)`

📧 邮件系统函数

`send_email($toEmail, $toName, $subject, $body)`

🎯 业务逻辑函数

`generate_unique_icp_number()`

`is_premium_number($number)`

`check_if_number_is_premium($number)`

🛠️ 工具函数

`redirect($url, $statusCode = 302)`

`current_url()`

`sanitizeInput($input)`

`isValidDomain($domain)`

`modify_url($new_params)`

🔧 系统工具函数

`is_installed()`

`log_memory_usage($message)`

📊 性能优化函数

内存管理

安全配置

🚨 错误处理

异常处理原则

日志记录

💡 使用建议

最佳实践