测试驱动智能体开发：用图分析解决AI编程的代码回归难题
2026/8/24 17:33:06
Patchwork UTF-8 完整 API 清单：60+个图形簇感知函数一次讲透（附速查表）
【免费下载链接】utf8Portable and performant UTF-8, Unicode and Grapheme Clusters for PHP项目地址: https://gitcode.com/gh_mirrors/ut/utf8
在 PHP 项目中处理中文、emoji 等多字节字符时，strlen、substr等原生字符串函数常常会"数错字、切坏字"。Patchwork UTF-8为 PHP 提供了一套完整、可移植、高性能的UTF-8 / Unicode / 图形簇（Grapheme Clusters）处理函数库，一个Patchwork\Utf8类就镜像了 50+ 个原生字符串函数，再配合土耳其语专用类、启动引导类和 mbstring/iconv/intl 兼容层，累计提供 60 多个图形簇感知函数。本文将这份 API 清单按使用场景分组一次讲透，并附上速查表，方便你快速检索。
为什么 PHP 原生字符串函数"不认识"中文？
PHP 内置的字符串函数把字符串当作字节来处理。而一个汉字在 UTF-8 里占 3 个字节，emoji 占 4 个字节，"中🇨🇳"这种组合字符更是由多个码点拼成一个可见字（即"图形簇"）。直接调用substr('中文', 0, 1)会得到乱码。
Patchwork UTF-8 的核心思路是：用与原生命名完全一致的函数，但内部按图形簇计算。你几乎不需要学习新 API——把strlen换成Utf8::strlen即可，参数和行为与原生函数一一对应。
30 秒上手：Bootup 引导与请求过滤
安装（composer 环境）后，只需在应用启动早期调用引导类，即可开启兼容层并配置好 UTF-8 环境，源码位于src/Patchwork/Utf8/Bootup.php：
Bootup::initAll()—— 一键启用 mbstring / iconv / intl 纯 PHP 兼容层，并配置 PHP 为 UTF-8；Bootup::filterRequestUri()—— URL 非 UTF-8 时自动重定向到 UTF-8 编码版本；Bootup::filterRequestInputs()—— 将 HTTP 输入统一规范化为 UTF-8 NFC。
这三步做完，后续的 60+ 个函数即可安全使用。
60+ 函数速查表：按场景分组
以下函数均位于src/Patchwork/Utf8.php中的Patchwork\Utf8类，全部为静态方法，直接Utf8::函数名()调用即可。
1️⃣ 环境搭建与字符串体检（4 个）
| 函数 | 作用（长尾场景） |
|---|---|
isUtf8() | 判断字符串是否为合法 UTF-8 编码，入库前防乱码必备 |
filter() | 规范化为 UTF-8 NFC，可自动从 CP-1252 转换 |
toAscii() | 将 UTF-8 转写为纯 ASCII（如 "café" → "cafe"） |
wrapPath() | Windows 及其他系统下的 Unicode 文件路径访问封装 |
2️⃣ 无差别匹配与终端显示（3 个）
| 函数 | 作用 |
|---|---|
strtocasefold() | Unicode 大小写折叠，用于"无视大小写"的精确比对 |
strtonatfold() | 大小写敏感的自然排序比对转换 |
strwidth() | 计算字符串在终端打印时的显示宽度（中文算 2 格） |
3️⃣ 输入与编解码（5 个）
| 函数 | 作用 |
|---|---|
filter_input() | 按图形簇感知的filter_input镜像版 |
filter_input_array() | 批量过滤 HTTP 输入数组 |
json_decode() | 自动处理带 BOM 或编码异常的 JSON 字符串 |
utf8_encode()/utf8_decode() | UTF-8 与 CP-1252 双向转换（原生函数已废弃，这是替代方案） |
4️⃣ 长度、定位与截取（12 个，最常用）
| 函数 | 对应原生 | 一句话说明 |
|---|---|---|
strlen() | strlen | 按"可见字符"数长度，中文 emoji 不再数错 |
strpos()/stripos() | strpos | 查找子串位置，不区分大小写版自动做 Unicode 折叠 |
strrpos()/strripos() | strrpos | 从末尾查找子串位置 |
strstr()/stristr() | strstr | 返回命中位置及其后的全部内容 |
strrchr()/strrichr() | strrchr | 返回最后一次命中及其后内容 |
substr() | substr | 安全截取 UTF-8 子串，绝不切出半个汉字 |
5️⃣ 修剪、替换与重组（13 个）
| 函数 | 对应原生 | 一句话说明 |
|---|---|---|
ltrim()/rtrim()/trim() | 同名 | 按图形簇修剪首尾空白或指定字符 |
substr_compare() | substr_compare | 比较两个字符串的部分片段 |
substr_count() | substr_count | 统计子串出现次数 |
substr_replace() | substr_replace | 在任意位置替换片段 |
str_split() | str_split | 按字符数安全拆分，不会劈开多字节字符 |
strcspn()/strspn() | 同名 | 计算不在/在字符集中的连续长度 |
strpbrk() | strpbrk | 返回字符集中首个出现的字符位置 |
strtr() | strtr | 批量字符映射替换 |
str_shuffle() | str_shuffle | 按图形簇打乱（emoji 组合不会被拆散） |
strrev() | strrev | 安全反转字符串 |
str_pad() | str_pad | 按显示宽度补白，中文对齐不再错位 |
wordwrap() | wordwrap | 按图形簇宽度自动折行 |
str_word_count() | str_word_count | 统计单词数 |
6️⃣ 大小写与字符级操作（7 个）
| 函数 | 对应原生 | 一句话说明 |
|---|---|---|
strtolower()/strtoupper() | 同名 | 基于 Unicode 的大小写转换（含多字符转换，如德语 ß → SS） |
ucfirst()/lcfirst() | 同名 | 首字符转大写/小写 |
ucwords() | ucwords | 每个单词首字母大写 |
str_ireplace() | str_ireplace | 不区分大小写的 Unicode 替换 |
chr() | chr | 码点转 UTF-8 字符 |
ord() | ord | UTF-8 字符转码点 |
count_chars() | count_chars | 按码点统计字符分布 |
7️⃣ 比较与格式化（8 个）
| 函数 | 对应原生 | 一句话说明 |
|---|---|---|
strcmp()/strnatcmp() | 同名 | 字节序比较 / 自然排序比较 |
strcasecmp()/strnatcasecmp() | 同名 | 忽略大小写的两种比较 |
strncmp()/strncasecmp() | 同名 | 限定长度的比较 |
number_format() | number_format | 数字本地化格式化（图形簇感知分隔符） |
💡 小技巧：几乎所有函数名都能与 PHP 原生函数"对号入座"，迁移老代码时只需把全局函数名加一个
Utf8::前缀即可。
土耳其语大小写的专门方案：TurkishUtf8
普通strtolower('I')会得到i，但在土耳其语中İ的小写是ı（无点 i），这是国际开发中最经典的"坑"。Patchwork\TurkishUtf8（源码位于src/Patchwork/TurkishUtf8.php）完整克隆了Patchwork\Utf8的全部功能，并重写了strtolower、strtoupper、ucfirst、ucwords、str_ireplace、stripos等 10 个大小写相关函数以适配土耳其语规则。做国际化产品时，建议根据用户区域动态二选一。
兼容层：mbstring / iconv / intl 没装也不怕
除了 60+ 个类方法，本库还内置纯 PHP 实现的"移植层"，当服务器缺少扩展时自动兜底，源码在src/Patchwork/PHP/Shim/目录：
- mbstring：
mb_strlen、mb_substr、mb_strpos、mb_convert_encoding等 30+ 个函数（见src/Patchwork/PHP/Shim/Mbstring.php）； - iconv：
iconv、iconv_strlen、iconv_mime_decode等（见src/Patchwork/PHP/Shim/Iconv.php）； - intl：
Normalizer规范化类与grapheme_*函数族（见src/Patchwork/PHP/Shim/Intl.php，顶层入口为src/Normalizer.php）； - utf8_encode / utf8_decode：PHP 8.2 起原生函数被废弃，这里提供永久替代。
这意味着你的应用即使在"裸 PHP"服务器上也能正确跑中文。
核心文件路径索引
- 主函数库：
src/Patchwork/Utf8.php - 土耳其语扩展：
src/Patchwork/TurkishUtf8.php - 启动引导：
src/Patchwork/Utf8/Bootup.php - 兼容性层：
src/Patchwork/PHP/Shim/ - 最佳拟合转换表（UTF-8 → 代码页）：
src/Patchwork/Utf8/data/ - 测试用例（可当文档读）：
tests/Utf8/、tests/PHP/Shim/ - 打包配置：
composer.json（包名patchwork/utf8，Apache-2.0 / GPL-2.0 双许可）
常见问题（FAQ）
Q1：必须安装 mbstring 或 intl 扩展吗？不需要。只要pcre带 Unicode 支持（绝大多数环境默认满足），本库纯 PHP 实现即可完整工作。
Q2：strlen和mb_strlen我该用哪个？推荐统一走Utf8::strlen风格。它优先复用原生扩展（有扩展时性能最佳），无扩展时自动降级，行为在所有服务器上一致。
Q3：图形簇（Grapheme Cluster）到底是什么？它是"用户眼中看到一个字符"的最小单元，例如 emoji 国旗 🇨🇳 由两个区域指示符组成、"e + 组合重音" 也是两个码点。本库全部函数都按图形簇而非字节/码点计算，这正是它区别于普通多字节处理的关键。
Q4：如何验证我的环境配置正确？先跑Bootup::initAll()，再用Utf8::isUtf8()抽查一段来自外部的字符串，最后用Utf8::strlen('中文测试')应得到 4 而不是 12 字节。
小结
Patchwork UTF-8 的价值一句话概括：一套与原生命名零差异、图形簇感知、不挑服务器环境的 PHP 字符串函数库。上文速查表覆盖 55 个核心镜像函数 + Bootup 引导 3 个 + 土耳其语重写 10 个 + 兼容层 30+ 个函数，总计 60 余个。建议收藏本文，遇到"中文被切坏、emoji 数错、大小写不灵"时，直接按分组查表即可。
【免费下载链接】utf8Portable and performant UTF-8, Unicode and Grapheme Clusters for PHP项目地址: https://gitcode.com/gh_mirrors/ut/utf8
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考