README

基于 Hyperf 框架的 PHP 扩展包，提供基础工具类、助手函数、全局中间件、基础验证Request类、基础资源Resource类等。

环境要求

• PHP >= 8.1
• Hyperf >= 3.1

安装

composer require tgkw-adc/helper

快速开始

1. 助手函数

use function TgkwAdc\cfg; use function TgkwAdc\redis; use function TgkwAdc\toRmb; use function TgkwAdc\math_add; // 获取配置 $config = cfg('app.name', 'default'); // 获取 Redis 实例 $redis = redis('default'); // 数字转中文大写金额 echo toRmb(123.45); // 壹佰贰拾叁元肆角伍分 // 精确数学运算 echo math_add('0.1', '0.2'); // 0.30

2. API 响应

use TgkwAdc\Helper\ApiResponseHelper; // 成功响应 return ApiResponseHelper::success($data, '操作成功'); // 错误响应 return ApiResponseHelper::error('参数错误', $errors, null, 400);

3. JWT 认证

use TgkwAdc\Helper\JwtHelper; // 初始化 JwtHelper::init(); // 生成令牌 $token = JwtHelper::createToken(['user_id' => 123], 3600); // 解析令牌 $payload = JwtHelper::parseToken($token); // 从请求获取载荷 $payload = JwtHelper::getPayloadFromRequest($request);

4. 日志记录

use TgkwAdc\Helper\Log\LogHelper; // 基本日志 LogHelper::info('用户登录', ['user_id' => 123]); LogHelper::error('操作失败', ['error' => '数据库连接超时']); // 业务日志 LogHelper::business('订单创建', ['order_id' => 456], 'business', 'order-create'); // 异常日志 LogHelper::exception($exception, '处理异常', ['user_id' => 123]);

5. 枚举注解

use TgkwAdc\Annotation\EnumCode; use TgkwAdc\Annotation\EnumCodePrefix; use TgkwAdc\Trait\EnumCodeGet; #[EnumCodePrefix(prefixCode: 1000)] enum UserStatus: int { use EnumCodeGet; #[EnumCode('正常', ['en' => 'Normal', 'zh_hk' => '正常'])] case NORMAL = 1; #[EnumCode('禁用', ['en' => 'Disabled', 'zh_hk' => '禁用'])] case DISABLED = 2; } // 使用 $status = UserStatus::NORMAL; echo $status->getMsg(); // 正常 echo $status->getCode(); // 100001 echo $status->getI18nMsg('en'); // Normal

详细功能

助手函数

配置和缓存

• cfg($key, $default) - 获取配置值
• redis($pool) - 获取 Redis 实例

字符串处理

• mb_trim($str, $char, $encoding) - 多字节字符串修剪
• mb_ltrim($str, $char, $encoding) - 多字节左修剪
• mb_rtrim($str, $trim, $encoding) - 多字节右修剪
• safeGetValue($string) - SQL 安全处理

数字处理

• toRmb($num) - 数字转中文大写金额
• numToCn($num) - 阿拉伯数字转中文数字
• priceFormat($price, $format) - 价格格式化
• math_add($a, $b, $scale) - 精确加法
• math_sub($a, $b, $scale) - 精确减法
• math_mul($a, $b, $scale) - 精确乘法
• math_div($a, $b, $scale) - 精确除法
• math_mod($a, $b) - 精确求余
• math_comp($a, $b, $scale) - 数值比较

数组处理

• object_array($array) - 对象转数组
• second_array_unique_bykey($arr, $key) - 二维数组去重
• percentArray($array) - 数组百分比转换

日期时间

• getDateYMD($startDate, $endDate, $type) - 获取日期范围
• getMonthsCovered($startDate, $endDate) - 计算跨越月数
• getDiffDay($startDate, $endDate) - 计算相差天数
• getDiffYear($startDate, $endDate) - 计算相差年数
• delHis($date) - 去除时分秒
• isDateValid($date, $formats) - 校验日期格式
• isDateTime($dateTime) - 校验日期时间

工具函数

• findNum($string) - 提取字符串中的数字
• handelUrlAliasParam($alias, $urlPatch) - 处理 URL 参数
• getRate($num) - 比例转百分比
• isJson($content) - 检查 JSON 格式
• getCollectionRate($val1, $val2) - 计算收缴率
• createNonceStr($length) - 生成随机字符串

中间件

语言检测中间件

use TgkwAdc\Middleware\LocaleMiddleware; // 在 config/autoload/middlewares.php 中注册 return [ 'http' => [ LocaleMiddleware::class, ], ];

支持的语言检测方式：

• URL 参数 ?lang=zh
• 请求体参数 {"lang": "zh"}
• Accept-Language 头
• X-Language 头
• Cookie 中的 locale

请求追踪中间件

use TgkwAdc\Middleware\TraceIdMiddleware; // 自动为每个请求生成唯一追踪ID

资源类

基础资源类

use TgkwAdc\Resource\BaseResource; class UserResource extends BaseResource { public function toArray(): array { return [ 'id' => $this->id, 'name' => $this->name, 'email' => $this->email, 'created_at' => $this->formatDate($this->created_at), ]; } } // 使用 return new UserResource($user) ->withMeta(['total' => 100]) ->withStats(['views' => 50]);

日志系统

配置日志

复制配置文件：

cp vendor/tgkw-adc/helper/src/Helper/Log/logger.example.php config/autoload/logger.php

日志通道

• default - 默认日志
• business - 业务日志
• access - 访问日志
• system - 系统日志
• exception - 异常日志

自定义日志文件名

// 按模块分类 LogHelper::info('订单创建', ['order_id' => 456], 'business', 'order-create'); // 按日期分类 $date = date('Y-m-d'); LogHelper::info('每日统计', ['count' => 100], 'statistics', 'default', "daily-{$date}"); // 按用户分类 LogHelper::info('用户操作', ['action' => 'login'], 'user', 'default', "user-{$userId}");

国际化支持

语言常量

use TgkwAdc\Constants\LocaleConstants; // 支持的语言 $locales = LocaleConstants::getSupportedLocaleCodes(); // ['zh' => 'zh_CN', 'en' => 'en_US', 'zh_hk' => 'zh_HK', 'zh_tw' => 'zh_TW'] // 默认语言 $default = LocaleConstants::getDefaultLocale(); // zh_CN

国际化助手

use TgkwAdc\Helper\Intl\I18nHelper; // 获取当前语言 $locale = I18nHelper::getNowLang(); // 获取翻译文本 $text = I18nHelper::getText('welcome.message', ['name' => 'John']);

配置说明

JWT 配置

// config/autoload/jwt.php return [ 'secret' => env('JWT_SECRET', 'your-secret-key'), 'alg' => env('JWT_ALG', 'HS256'), ];

日志配置

// config/autoload/logger.php return [ 'default' => [ 'handler' => [ 'class' => Monolog\Handler\RotatingFileHandler::class, 'constructor' => [ 'filename' => BASE_PATH . '/runtime/logs/app.log', 'level' => Monolog\Level::Info, 'maxFiles' => 30, ], ], 'formatter' => [ 'class' => TgkwAdc\Helper\Log\CustomJsonFormatter::class, ], 'processors' => [ TgkwAdc\Helper\Log\AppendRequestIdProcessor::class, ], ], ];

开发工具

代码格式化

vendor/bin/php-cs-fixer fix src

静态分析

vendor/bin/phpstan analyse --memory-limit 1024M -l 0 ./src

# 新建1.0.1版本标签 git tag -a 1.0.1 -m "1.0.1版本" # 标签推送到github git push origin 1.0.1