webman-tech/common-utils

Maintainers

Details

github.com/webman-tech/common-utils

Source

Issues

Installs: 71

Dependents: 22

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/webman-tech/common-utils

v5.0.1 2025-11-24 05:27 UTC

Requires

Requires (Dev)

MIT 3a1ce0442e9776146b2a840ce666cf3f91105afa

This package is auto-updated.

Last update: 2025-11-24 06:13:03 UTC

README

本项目是从 webman-tech/components-monorepo 自动 split 出来的，请勿直接修改

通用工具类组件，屏蔽 Webman/Laravel 等框架差异，提供统一的核心功能 API

功能介绍

common-utils 是一个通用工具类组件，旨在屏蔽不同框架（如 Webman、Laravel 等）之间的差异，提供统一的核心功能 API。该组件包含了一系列常用的工具类和函数，方便在不同框架环境中使用。

主要功能包括：

  • 统一的配置读取接口
  • 统一的日志记录接口
  • 统一的容器访问接口
  • 运行环境检测
  • JSON 编码/解码增强
  • 本地路径管理
  • 环境变量处理
  • 字符编码处理
  • 语言区域设置
  • 视图渲染

安装与配置

通过 Composer 安装：

composer require webman-tech/common-utils

该组件无特殊配置要求，直接使用即可。

核心类说明

Config

统一配置读取类，屏蔽不同框架之间的配置读取差异。

主要方法：

  • get(): 读取配置项，支持点号分隔的嵌套配置
  • requireFromConfigPath(): 从 config 目录中引入配置文件

Log

统一日志记录类，提供跨框架的日志记录接口。

主要方法：

  • channel(): 获取日志通道实例

Container

统一容器访问类，屏蔽不同框架之间的依赖注入容器差异。

主要方法：

  • get(): 从容器中获取实例
  • has(): 检查容器中是否存在某项
  • make(): 创建实例

Runtime

运行环境检测类，用于检测当前运行环境。

主要方法：

  • isWebman(): 检测是否在 Webman 环境下
  • isLaravel(): 检测是否在 Laravel 环境下
  • isTest(): 检测是否在测试环境下
  • isCli(): 检测是否在 CLI 模式下
  • isWorkerman(): 检测是否在 Workerman 环境下

Json

JSON 处理增强类，提供更强大的 JSON 编码和解码功能。

主要方法：

  • encode(): JSON 编码，支持特殊对象和表达式
  • decode(): JSON 解码

Local

本地路径管理类，用于管理项目中的各种路径。

主要方法：

  • getBasePath(): 获取项目基础路径
  • getRuntimePath(): 获取项目运行时路径
  • getConfigPath(): 获取配置文件路径
  • getAppPath(): 获取应用目录路径
  • getVendorPath(): 获取 vendor 目录路径
  • combinePath(): 拼接路径
  • getIp(): 获取本机 IP
  • getPort(): 获取本地服务端口

EnvAttr

环境变量处理类，提供便捷的环境变量操作接口。

主要方法：

  • get(): 获取环境变量
  • set(): 设置环境变量
  • has(): 检查环境变量是否存在
  • load(): 批量加载环境变量

Encoding

字符编码处理类，用于处理各种字符编码转换。

主要方法：

  • toUTF8(): 转换为 UTF-8 编码
  • detect(): 检测字符串编码
  • convert(): 转换编码

Lang

语言区域设置类，用于处理多语言环境。

主要方法：

  • getLocale(): 获取当前语言区域
  • setLocale(): 设置当前语言区域

View

视图渲染类，提供简单的视图渲染功能。

主要方法：

  • renderPHP(): 渲染 PHP 视图文件

使用方法

配置读取

使用 Config 类统一读取不同框架的配置：

use WebmanTech\CommonUtils\Config;

// 读取配置项，支持点号分隔的嵌套配置
$value = Config::get('app.name', 'default');

// 支持闭包作为默认值
$value = Config::get('app.name', function() {
    return 'dynamic default value';
});

// 从 config 目录中引入配置文件
$configArray = Config::requireFromConfigPath('database');

日志记录

使用 Log 类统一记录日志：

use WebmanTech\CommonUtils\Log;

// 获取默认日志通道
$logger = Log::channel();
$logger->info('这是一条信息日志');

// 获取指定日志通道
$logger = Log::channel('error');
$logger->error('这是一条错误日志');

// 直接记录日志
Log::channel()->warning('警告信息');

视图渲染

使用 View 类进行视图渲染：

use WebmanTech\CommonUtils\View;

View::renderPHP('view/index.php', ['name' => '张三']);

语言

使用 Lang 类进行语言处理：

use WebmanTech\CommonUtils\Lang;

echo Lang::getLocale(); // 获取当前语言
Lang::setLocale('zh-CN'); // 设置当前语言

容器访问

使用 Container 类统一访问不同框架的依赖注入容器：

use WebmanTech\CommonUtils\Container;

// 从容器中获取实例
$db = Container::get('db');

// 检查容器中是否存在某项
if (Container::has('cache')) {
    $cache = Container::get('cache');
}

// 创建实例
$http = Container::make('http', ['port' => 8080]);

除了静态方法外，还提供了对应的便捷函数：

use function WebmanTech\CommonUtils\container_get;
use function WebmanTech\CommonUtils\container_has;
use function WebmanTech\CommonUtils\container_make;

$db = container_get('db');

if (container_has('cache')) {
    $cache = container_get('cache');
}

$http = container_make('http', ['port' => 8080]);

运行环境检测

使用 Runtime 类检测当前运行环境：

use WebmanTech\CommonUtils\Runtime;

// 检测是否在 Webman 环境下
if (Runtime::isWebman()) {
    echo "当前运行在 Webman 框架中";
}

// 检测是否在 Laravel 环境下
if (Runtime::isLaravel()) {
    echo "当前运行在 Laravel 框架中";
}

// 检测是否在 CLI 模式下
if (Runtime::isCli()) {
    echo "当前在命令行模式下";
}

// 检测是否在 Workerman 环境下
if (Runtime::isWorkerman()) {
    echo "当前运行在 Workerman 环境中";
}

JSON 处理

使用 Json 类进行增强的 JSON 编码和解码：

use WebmanTech\CommonUtils\Json;

// JSON 编码
$data = ['name' => '张三', 'age' => 30];
$jsonString = Json::encode($data);

// JSON 解码
$decodedData = Json::decode($jsonString);

// 处理特殊对象
class User {
    public $name = '张三';
    public $age = 30;
}

$user = new User();
$jsonString = Json::encode($user);

// 处理 JavaScript 表达式
use WebmanTech\CommonUtils\Json\Expression;

$data = [
    'callback' => new Expression('function() { alert("Hello"); }')
];
$jsonString = Json::encode($data);
// 输出: {"callback":function() { alert("Hello"); }}

本地路径管理

使用 Local 类管理本地路径：

use WebmanTech\CommonUtils\Local;

// 获取项目基础路径
$basePath = Local::getBasePath();

// 获取项目运行时路径
$runtimePath = Local::getRuntimePath();

// 获取配置文件路径
$configPath = Local::getConfigPath();

// 获取 app 路径
$appPath = Local::getAppPath();

// 获取 vendor 路径
$vendorPath = Local::getVendorPath();

// 拼接路径
$combinedPath = Local::combinePath($basePath, 'storage', 'logs');

// 获取本机 IP
$localIp = Local::getIp();

环境变量处理

使用 EnvAttr 类处理环境变量：

use WebmanTech\CommonUtils\EnvAttr;

// 获取环境变量
$value = EnvAttr::get('APP_ENV', 'production');

// 设置环境变量
EnvAttr::set('CUSTOM_KEY', 'custom_value');

// 检查环境变量是否存在
if (EnvAttr::has('APP_DEBUG')) {
    echo "APP_DEBUG 已设置";
}

// 批量加载环境变量
$envVars = [
    'DB_HOST' => 'localhost',
    'DB_PORT' => 3306
];
EnvAttr::load($envVars);

字符编码处理

使用 Encoding 类处理字符编码：

use WebmanTech\CommonUtils\Encoding;

// 转换为 UTF-8 编码
$utf8String = Encoding::toUTF8($originalString);

// 检测字符串编码
$encoding = Encoding::detect($string);

// 转换编码
$convertedString = Encoding::convert($string, 'GBK', 'UTF-8');

最佳实践

  1. 在多框架项目中使用统一的工具类接口，避免直接调用框架特定方法
  2. 利用 Runtime 类进行环境检测，编写兼容性更好的代码
  3. 使用 Json 类替代原生 json_encode/json_decode，获得更好的错误处理和特殊类型支持
  4. 通过 Config 类统一管理配置读取，提高代码可维护性
  5. 使用 Local 类管理路径，确保在不同环境中的路径正确性
  6. 合理使用 EnvAttr 类处理环境变量，便于配置管理
  7. 使用 Container 类访问依赖注入容器，提高代码解耦性
  8. 通过 Lang 和 View 类处理国际化和视图渲染需求

注意事项

  1. 该组件旨在提供统一接口，具体实现会根据运行环境自动适配
  2. 在不支持的环境中使用某些功能时会抛出 InvalidArgumentException 异常
  3. JSON 处理类对特殊值（如 INF、NAN）和资源类型进行了特殊处理
  4. 路径管理类支持测试环境的特殊路径配置