README

一个面向 PHP 项目的轻量级公共支持库，封装日常开发中常用的工具类、助手函数和基础组件，零业务依赖、开箱即用。

特性

🚀 零业务依赖：仅依赖 guzzlehttp/guzzle、nesbot/carbon、ezyang/htmlpurifier 等通用库
🧰 丰富工具集：覆盖 HTTP、字符串、数组、文件、时间、加密、网络、树、JSON、HTML 等常用场景
🇨🇳 本土化增强：内置身份证、统一社会信用代码、MAC 地址、IP、ISO 3166、地理位置等中国场景工具
🧱 统一基类：提供 BaseObject、Trait（HasAttributes / HasHttpRequest / Macroable）等基础设施
✅ 完整测试：基于 PHPUnit 11 编写单元测试
🎨 代码风格：使用 friendsofphp/php-cs-fixer 统一编码风格

环境需求

PHP ^8.2（支持 8.2 / 8.3 / 8.4+）
扩展：ext-curl、ext-dom、ext-json、ext-openssl、ext-mbstring、ext-simplexml、ext-libxml、ext-fileinfo

安装

composer require larva/support -vv

快速开始

<?php

use Larva\Support\HttpClient;
use Larva\Support\StringHelper;
use Larva\Support\Number;
use Larva\Support\TimeHelper;
use Larva\Support\IDCard;

// 1. 发起一个 JSON HTTP 请求
$client = new HttpClient();
$data = $client->getJSON('https://api.example.com/users', ['page' => 1]);

// 2. 生成 UUID、随机字符串
$uuid = StringHelper::createUuid('usr_');
$rand = StringHelper::random(16);

// 3. 金额格式化（人民币）
echo Number::rmb(100.5); // ￥100.50

// 4. 友好的时间显示
echo TimeHelper::humanDateTime(time() - 3600); // 1 小时前

// 5. 校验中国大陆身份证
if (IDCard::validate('11010519491231002X')) {
    echo IDCard::getSex('11010519491231002X');      // 男 / 女
    echo IDCard::getBirthday('11010519491231002X'); // 1949-12-31
    echo IDCard::getLocation('11010519491231002X'); // 北京市 / 朝阳区
}

组件一览

类 / Trait	说明
`BaseObject`	基础对象类，支持数组式属性访问与配置初始化
`ArrayHelper`	数组 / 对象取值、合并、映射等操作
`ArrayAccessible`	让对象可被 `foreach` 遍历
`Collection`	集合类，提供 map / filter / reduce 等链式操作
`Config`	轻量级配置容器
`FileHelper`	文件 / 目录读写、复制、遍历等常用操作
`HtmlHelper`	HTML 安全过滤、编码（基于 HTMLPurifier）
`HttpClient`	基于 Guzzle 的 HTTP 客户端，支持 JSON、表单、文件上传
`HttpResponse`	统一的 HTTP 响应封装
`IDCard`	中国大陆身份证号校验、解析出生日期 / 性别 / 地区
`IPHelper`	IP 解析、内网段判断、IP ↔ 长整型互转
`ISO3166`	国家 / 地区代码数据
`Json`	JSON 编码 / 解码工具
`LBSHelper`	地理位置（LBS）相关工具
`MacAddres`	MAC 地址校验与格式化
`Number`	数字、金额格式化（人民币、千分位等）
`SSLCertificate`	SSL 证书解析
`Socket`	Socket 通信
`SqlHelper`	SQL 拼接助手
`StringHelper`	字符串处理：UUID、随机数、命名风格转换、截断等
`TimeHelper`	时间格式化、人性化时间显示（基于 Carbon）
`Tree`	树形结构构建与遍历
`UnifiedSocialCreditIdentifier`	统一社会信用代码校验
`Url`	URL 解析、拼接与签名
`Traits\HasAttributes`	对象属性读写（类似 Yii AR）
`Traits\HasHttpRequest`	HTTP 请求相关通用方法
`Traits\Macroable`	宏能力（动态扩展类方法）

完整的接口说明请参考 src/ 目录下各类的 PHPDoc 注释。

使用示例

HTTP 客户端

use Larva\Support\HttpClient;
use Larva\Support\Exception\ConnectionException;

$client = new HttpClient([
    'base_uri' => 'https://api.example.com',
    'timeout'  => 10,
]);

// 发起 JSON 请求
$user = $client->getJSON('/users/1');

// 提交表单
$client->post('/users', ['name' => 'Tom', 'age' => 18]);

// 上传文件
$client->upload('/avatar', '/path/to/file.png', ['field' => 'file']);

字符串助手

use Larva\Support\StringHelper;

StringHelper::random(32);                  // 随机字符串
StringHelper::createUuid();                // UUID v4
StringHelper::camel('user_name');          // userName
StringHelper::snake('UserName');           // user_name
StringHelper::studly('user_profile');      // UserProfile
StringHelper::mask('13800001234', 3, 7);   // 138****1234

数字与金额

use Larva\Support\Number;

Number::float(1.236, 2);    // 1.24
Number::priceFormat(9.8);   // 9.80
Number::rmb(199.9);         // ￥199.90
Number::toChinese(100.50);  // 壹佰元伍角

时间助手

use Larva\Support\TimeHelper;

TimeHelper::humanDateTime('2024-01-01 12:00:00'); // 相对时间描述
TimeHelper::timestampToDateTime(1704067200);      // 2024-01-01 08:00:00

数组 / 集合

use Larva\Support\ArrayHelper;
use Larva\Support\Collection;

$value = ArrayHelper::getValue($array, 'user.profile.name', 'default');

$collection = new Collection([1, 2, 3, 4, 5]);
$result = $collection->map(fn ($v) => $v * 2)
                    ->filter(fn ($v) => $v > 4)
                    ->values();

树形结构

use Larva\Support\Tree;

$rows = [
    ['id' => 1, 'parent_id' => 0, 'name' => 'A'],
    ['id' => 2, 'parent_id' => 1, 'name' => 'B'],
    ['id' => 3, 'parent_id' => 1, 'name' => 'C'],
];

$tree = Tree::build($rows, 'id', 'parent_id', 'children');

身份证

use Larva\Support\IDCard;

IDCard::validate('11010519491231002X'); // true / false
IDCard::getSex('11010519491231002X');   // '男' / '女'
IDCard::getBirthday('11010519491231002X'); // '1949-12-31'
IDCard::getAge('11010519491231002X');   // int
IDCard::getLocation('11010519491231002X'); // 行政区划

统一社会信用代码

use Larva\Support\UnifiedSocialCreditIdentifier;

UnifiedSocialCreditIdentifier::validate('91110000600037341L'); // true

开发与测试

克隆仓库后，安装依赖：

composer install

运行单元测试：

composer test

检查并自动修复代码风格：

composer check-style   # 仅检查
composer fix-style     # 自动修复

本项目使用 friendsofphp/php-cs-fixer 统一编码风格，提交前请确保通过检查。

异常体系

src/Exception/ 目录提供了一系列业务无关的基础异常类，便于业务层统一处理：

Exception：根异常
RuntimeException / InvalidCallException / InvalidConfigException / InvalidUrlException
HttpClientException / ConnectionException / RequestException
FileException / FileNotFoundException
NotSupportedException / UnknownMethodException / UnknownPropertyException

路线图

持续完善单元测试覆盖率
增加更多中国本土化工具（如车牌号校验等）
提供更丰富的 TypeScript / IDE 提示

贡献

欢迎提交 Issue 与 Pull Request。提交前请：

通过 composer test 全部测试
通过 composer check-style 风格检查
在 PR 中描述清楚变更背景与影响范围

安全

如发现安全漏洞，请联系：support@larva.com.cn，请勿在公开 Issue 中披露。

许可证

本项目基于 MIT 协议发布。

larva / support

Maintainers

Package info

Statistics

Security