PHP grapheme_extract 怎样按字素长度截取文本

如果需求是“最多保留两个用户看到的字符”，直接用 substr 或按 strlen 计算并不稳妥：UTF-8 字符可能占多个字节，一个用户感知的字素簇还可能由多个 Unicode 码点组成。grapheme_extract 的迁移价值在于，它能以默认字素簇为单位截取，并在簇边界结束，避免把组合字符从中间拆开。

官方地址：https://www.php.net/manual/en/function.grapheme-extract.php

按字素长度截取时，把 type 保持为默认的 GRAPHEME_EXTR_COUNT，让 size 表示要取的默认字素簇数量；不要把字节数、UTF-8 字符数和用户感知的字素数混为一谈。

一、先明确这次迁移改的是什么

旧代码常见的做法是用 substr($text, 0, $limit)，或者先用 strlen 判断长度再截取。这些函数面对 UTF-8 时按字节工作，限制值一旦落在多字节字符中间，结果就可能出现不完整文本。即使改用按 Unicode 字符计数的方案，也不等于按默认字素簇计数。

本次迁移只解决一个明确任务：把输入字符串从开头取出指定数量的默认字素簇。函数要求输入是 UTF-8，且来自 PHP 的 intl 扩展；返回值是字符串，失败时返回 false。

二、用 GRAPHEME_EXTR_COUNT 按字素长度截取

省略 type 时，size 默认表示要提取的默认字素簇数量。显式写出 GRAPHEME_EXTR_COUNT 更适合迁移后的代码，因为读者能直接看到“按字素计数”，而不是把第三个参数留给猜测。

这里的 $limit 是数量，不是字节数。函数会在默认字素簇边界结束，因此组合附加符号不会被单独留在字符串开头，连接式表情也不会因为简单的字节切片而被拆散。示例中的文本仅用于说明输入形态，具体边界仍由 PHP 所使用的 Unicode 规则决定。

三、offset 和 next 怎样配合

offset 的单位是字节，不是第几个字素。它可以是零或正数，也可以是从字符串末尾计算的负数；如果正偏移落在 UTF-8 字符的中间，起点会移动到下一个字符边界。通过引用传入 $next 后，函数会把下一次起始位置写回这个变量，适合按字素簇循环处理。

这个循环里只有 strlen 用来判断字节游标是否到达末尾，并没有拿它当作用户字符数量。真正的分段单位由 GRAPHEME_EXTR_COUNT 决定，$next 负责把游标推进到下一段的字节起点。

四、迁移时区分三种 size 语义

官方函数把 size 的含义交给 type 控制，不能只看参数位置。按字素长度的迁移应优先使用默认的 GRAPHEME_EXTR_COUNT；另外两个常量适用于不同的上限约束。

第三个参数改成 GRAPHEME_EXTR_MAXBYTES 并不会把字节上限变成字素上限；它只是改变截取规则。迁移前应先确认业务限制写的是“用户看到的数量”“UTF-8 字符数量”还是“编码后字节数”。

五、旧代码风险和回归检查

迁移不应只替换函数名。建议至少覆盖以下输入：纯 ASCII、中文、多字节拉丁字符、组合附加符号、连接式表情、空字符串、size 为零，以及从中间字节偏移开始的调用。每个用例都要确认结果没有切断字素簇，并确认失败时不会被当成空字符串静默吞掉。

 'hello', 'size' => 3],
    ['text' => "Cafe\u{0301}", 'size' => 4],
    ['text' => '中文标题', 'size' => 2],
    ['text' => '😀🙂', 'size' => 1],
];

foreach ($cases as $case) {
    // 明确比较 false，避免把合法的空结果和调用失败混在一起。
    $value = grapheme_extract($case['text'], $case['size'], GRAPHEME_EXTR_COUNT);
    if ($value === false) {
        throw new RuntimeException('测试用例截取失败');
    }
    echo $value, PHP_EOL;
}
?>

六、迁移清单：什么时候可以替换完成

1. 确认输入统一为 UTF-8，并确认运行环境启用了 intl 扩展。
2. 把面向用户展示的长度约束改成 GRAPHEME_EXTR_COUNT，不要继续把字节数当字符数。
3. 需要继续扫描时，用引用参数接收 next，并检查游标确实前进。
4. 把 GRAPHEME_EXTR_MAXCHARS 和 GRAPHEME_EXTR_MAXBYTES 留给对应的协议或存储约束。
5. 回归测试覆盖组合字符、表情、中文、空输入、零长度、负 offset 和失败返回值。

如果旧代码的真实约束是数据库字段字节数，仍应先按字节预算设计，再决定是否需要在字素边界做二次截取；如果约束是用户看到的长度，GRAPHEME_EXTR_COUNT 才是更直接的表达。迁移完成的标志不是函数调用成功，而是计量单位、边界行为和失败处理都与业务约定一致。

总结

grapheme_extract 按字素长度截取的核心写法是：传入 UTF-8 文本、字素簇数量和 GRAPHEME_EXTR_COUNT，必要时用 offset 与 next 管理字节游标。迁移时先区分字素、UTF-8 字符和字节三种单位，再用组合字符、表情和边界偏移做回归，才能真正避免截断乱码或长度误判。

相关问题

• grapheme_extract 为什么要求输入使用 UTF-8？
• GRAPHEME_EXTR_COUNT 和 GRAPHEME_EXTR_MAXCHARS 有什么区别？
• offset 落在多字节字符中间时会发生什么？
• 什么时候应该用字节上限而不是字素簇上限？