签入版本

2026-10-08 17:50:29 +08:00
parent 809750b47e
commit e213a9b31d
444 changed files with 39366 additions and 37533 deletions
@@ -1,7 +1,7 @@
 # D. 公共函数速查

 :::tip 概述
-以下函数定义在 `app/common.php` 中，可在任何地方直接调用。
+以下函数定义在 `app/Helpers/helpers.php` 中（通过 `composer.json` 的 `autoload.files` 自动加载），可在任何地方直接调用。
 :::

 ## 字符串 / 加密
@@ -9,21 +9,25 @@
 | 函数 | 说明 | 签名 |
 |------|------|------|
 | `random_string($length)` | 生成随机字符串 | `string random_string(int $length = 16)` |
-| `encrypt_password($password, $salt)` | 密码加密（bcrypt） | `array encrypt_password(string $password, ?string $salt = null)` |
+| `encrypt_password($password, $salt)` | 密码加密（委托 PasswordService） | `array encrypt_password(string $password, ?string $salt = null)` |
 | `verify_password($password, $hash, $salt)` | 验证密码 | `bool verify_password(string $password, string $encryptPassword, string $salt)` |

 ## 文件处理

 | 函数 | 说明 | 签名 |
 |------|------|------|
-| `upload_file($formName, $type)` | 上传文件到临时目录 | `array upload_file(string $formName = 'file', string $type = 'file')` |
-| `save_file($fileUrl, $saveDir)` | 临时文件迁移到正式目录 | `string\|false save_file(string $fileUrl, string $saveDir = '')` |
-| `save_content(&$content, $saveDir)` | 处理富文本中的媒体文件 | `bool save_content(string &$content, string $saveDir = 'article')` |
+| `save_file($fileUrl, $saveDir)` | 临时文件迁移到正式目录 | `save_file(string $fileUrl, string $saveDir = '')` |
+| `save_content(&$content, $saveDir)` | 处理富文本中的媒体文件（迁移 + 域名替换） | `bool save_content(string &$content, string $saveDir = 'article')` |
+| `save_content_match(...)` | 富文本内单类 URL 匹配迁移（save_content 内部使用） | `void save_content_match(string $content, string $pattern, string $domainUrl, string $saveDir, array &$urlMap)` |
 | `get_file_url($path)` | 相对路径转完整 URL | `string get_file_url(string $path)` |
-| `create_file_path($saveDir, $ext)` | 生成文件存储路径 | `string create_file_path(string $saveDir = '', string $ext = '')` |
-| `save_remote_file($url, $saveDir)` | 保存远程文件 | `string\|false save_remote_file(string $url, string $saveDir = '')` |
+| `create_file_path($saveDir, $ext)` | 生成文件存储路径（按日期分目录） | `string create_file_path(string $saveDir = '', string $ext = '')` |
+| `save_remote_file($url, $saveDir)` | 保存远程文件 | `save_remote_file(string $url, string $saveDir = '')` |
 | `detect_image_ext($content)` | 根据内容检测图片后缀 | `?string detect_image_ext(string $content)` |

+:::info 上传入口不在这里
+HTTP 文件上传入口是 `POST /api/upload/uploadFile`（见 [7.1 文件上传全流程](/zh/tools/upload.html)），业务层的临时→正式迁移由 `HasFileProcessing` Trait 调用 `save_file()` / `save_content()` 完成。
+:::
+
 ## 驼峰 / 下划线转换

 | 函数 | 说明 | 签名 |
@@ -32,14 +36,18 @@
 | `camel_to_snake($str)` | 驼峰转下划线 | `string camel_to_snake(string $str)` |
 | `array_snake_to_camel($data)` | 数组键名下划线转驼峰（递归） | `array array_snake_to_camel(array $data)` |
 | `array_camel_to_snake($data, $except)` | 数组键名驼峰转下划线（递归） | `array array_camel_to_snake(array $data, array $except = [])` |
-| `is_camel_convert_enabled()` | 是否开启转换 | `bool is_camel_convert_enabled()` |
+| `is_camel_convert_enabled()` | 是否开启转换（读 `config('api.camel_snake_convert')`） | `bool is_camel_convert_enabled()` |
+| `convert_to_camel($data)` | 单条数据转驼峰（受开关控制） | `convert_to_camel($data)` |
+| `convert_list_to_camel($list)` | 列表数据转驼峰（受开关控制） | `array convert_list_to_camel(array $list)` |

 ## 工具函数

 | 函数 | 说明 | 签名 |
 |------|------|------|
-| `get_client_ip()` | 获取客户端 IP | `string get_client_ip()` |
-| `format_page_params($params)` | 格式化分页参数 | `array format_page_params(array $params)` |
+| `get_client_ip()` | 获取客户端 IP（经 ProxyMiddleware 受信代理解析） | `string get_client_ip()` |
+| `is_internal_ip($ip)` | 判断是否内网 / 回环地址 | `bool is_internal_ip(string $ip)` |
+| `format_page_params($params)` | 格式化分页参数（pageNo ≥ 1、pageSize 1~100） | `array format_page_params(array $params)` |
+| `build_tree($list, $parentId, $parentField)` | 平面列表组装为树 | `array build_tree(array $list, int $parentId = 0, string $parentField = 'parent_id')` |

 ## 使用示例

@@ -47,20 +55,24 @@
 // 生成随机字符串
 $str = random_string(32);

-// 密码加密
+// 密码加密与验证
 $result = encrypt_password('123456');
 // ['password' => '$2y$12$...', 'salt' => 'xK7pMn3qRt']
-
-// 验证密码
 $ok = verify_password('123456', $user->password, $user->salt);

-// 文件上传
-$result = upload_file('avatar', 'image');
-if (isset($result['error'])) {
-    return Result::fail($result['error']);
+// 临时文件迁移到正式目录（HasFileProcessing 内部即这样调用）
+$result = save_file($data['avatar'], 'user');
+if ($result === false) {
+    // 保留原值，避免误清空
 }

+// 相对路径补全域名
+$url = get_file_url($data['avatar']);
+
 // 驼峰转换
 camel_to_snake('createTime');    // 'create_time'
 snake_to_camel('create_time');   // 'createTime'
-```
+
+// 平面列表组装为树（树形模块 treeList 使用）
+$tree = build_tree($list, 0, 'parent_id');
+```