coduo/php-humanizer · 上手攻略

  • 仓库：coduo/php-humanizer
  • 链接：https://github.com/coduo/php-humanizer
  • 分类：PHP Utility · Humanize
  • 作者：Tom
  • 更新：2026-08-21

是什么

php-humanizer 是 coduo 团队开源的 PHP 库，核心功能是把程序员才看得懂的数据转成普通人能理解的形式——下划线字段名变空格分隔、罗马数字互转、字节数转 KB/MB/GB、时间差变自然语言。

和前文的 JavaScript 版 HumanizeDuration.js 不同，php-humanizer 更像一组「人类友好化」工具的合集，覆盖字符串、数字、集合、日期时间四大类。

当前版本 5.x，活跃维护，PHP >= 8.1。

解决什么问题

// 字段名列 → 人类可读标题
StringHumanizer::humanize('field_name');       // "Field Name"
StringHumanizer::humanize('user_id');          // "User id"

// 数字 → 序数词
NumberHumanizer::ordinalize(23);               // "23rd"

// 字节 → 带单位字符串
NumberHumanizer::binarySuffix(1048576);         // "1 MB"

// 数字 → 简短计量后缀
NumberHumanizer::metricSuffix(1240000);         // "1.24M"

适用场景：后台管理系统展示、API 文档自动生成、数据报告格式化、日志输出美化。

快速安装

composer require coduo/php-humanizer

要求：PHP >= 8.1。

⚠️ 建议通过 Composer 安装，不要直接 clone 源码（需要 autoload）。如果需要自定义分支可看 5.x 分支：https://github.com/coduo/php-humanizer/tree/5.x。

核心用法

字符串 humanize

use Coduo\PHPHumanizer\StringHumanizer;

// 下划线/驼峰转空格分隔标题（首字母大写）
StringHumanizer::humanize('field_name');         // "Field Name"
StringHumanizer::humanize('user_id');            // "User id"

// 第二个参数 false = 不首字母大写
StringHumanizer::humanize('field_name', false);   // "field name"

字符串截断

use Coduo\PHPHumanizer\StringHumanizer;

$text = 'Lorem ipsum dolorem si amet, lorem ipsum. Dolorem sic et nunc.';

// 按字符数截断到最近的完整单词
StringHumanizer::truncate($text, 8);             // "Lorem ipsum"
StringHumanizer::truncate($text, 8, '...');      // "Lorem ipsum..."
StringHumanizer::truncate($text, 2);             // "Lorem"

HTML 截断（保留标签）

use Coduo\PHPHumanizer\StringHumanizer;

$html = '<p><b>HyperText Markup Language</b> (HTML) is the standard markup language...</p>';

// 按字符数截断，同时保持标签有效
StringHumanizer::truncateHtml($html, 12, '');   // "HyperText Markup"

// 指定允许保留的标签白名单
StringHumanizer::truncateHtml($html, 75, '<b><i><u><em><strong><a><span>', '...');
// => '<b>HyperText Markup Language</b>, commonly referred to as <b>HTML</b>, is the standard <a href="...">markup...</a>'

Shortcode 清理

use Coduo\PHPHumanizer\StringHumanizer;

// 移除所有短代码内容，保留其余文本
$text = 'A text with [short]random[/short] [codes]words[/codes].';
StringHumanizer::removeShortcodes($text);         // "A text with ."

// 移除短代码标签但保留内容
StringHumanizer::removeShortcodeTags($text);      // "A text with random words."

数字 Ordinalize（序数词）

use Coduo\PHPHumanizer\NumberHumanizer;

// 输入整数，输出 "1st", "2nd", "3rd" 等
NumberHumanizer::ordinalize(0);     // "0th"
NumberHumanizer::ordinalize(1);     // "1st"
NumberHumanizer::ordinalize(2);     // "2nd"
NumberHumanizer::ordinalize(23);    // "23rd"
NumberHumanizer::ordinalize(1002, 'nl');  // "1002e"（荷兰语）
NumberHumanizer::ordinalize(-111);  // "-111th"

罗马数字互转

use Coduo\PHPHumanizer\NumberHumanizer;

// 整数 → 罗马数字
NumberHumanizer::toRoman(1);        // "I"
NumberHumanizer::toRoman(5);        // "V"
NumberHumanizer::toRoman(1300);    // "MCCC"

// 罗马数字 → 整数
NumberHumanizer::fromRoman("MMMCMXCIX");  // 3999
NumberHumanizer::fromRoman("V");          // 5
NumberHumanizer::fromRoman("CXXV");       // 125

Bytes → 二进制单位

use Coduo\PHPHumanizer\NumberHumanizer;

// 自动选择最高适用单位
NumberHumanizer::binarySuffix(0);              // "0 bytes"
NumberHumanizer::binarySuffix(1024);           // "1 kB"
NumberHumanizer::binarySuffix(1536);           // "1.5 kB"
NumberHumanizer::binarySuffix(1048576 * 5);   // "5 MB"
NumberHumanizer::binarySuffix(1073741824 * 2); // "2 GB"
NumberHumanizer::binarySuffix(1099511627776 * 3);  // "3 TB"
NumberHumanizer::binarySuffix(1325899906842624);    // "1.18 PB"

// 指定小数精度（0-3 位）
NumberHumanizer::preciseBinarySuffix(1024, 2);      // "1.00 kB"
NumberHumanizer::preciseBinarySuffix(1325899906842624, 3);  // "1.178 PB"

// 指定 locale（不同语言数字格式）
NumberHumanizer::binarySuffix(1536, 'pl');  // "1,5 kB"（波兰语逗号格式）

数字 → 公制后缀

use Coduo\PHPHumanizer\NumberHumanizer;

// k / M / B / T 等公制后缀（每3位一个单位）
NumberHumanizer::metricSuffix(-1);    // "-1"
NumberHumanizer::metricSuffix(0);     // "0"
NumberHumanizer::metricSuffix(1);     // "1"
NumberHumanizer::metricSuffix(101);   // "101"
NumberHumanizer::metricSuffix(1000); // "1k"
NumberHumanizer::metricSuffix(1240); // "1.2k"
NumberHumanizer::metricSuffix(1240000);   // "1.24M"
NumberHumanizer::metricSuffix(3500000);   // "3.5M"

// 指定 locale
NumberHumanizer::metricSuffix(1240000, 'pl');  // "1,24M"

Oxford 列表（牛津逗号）

use Coduo\PHPHumanizer\CollectionHumanizer;

// 最后一个元素前加 "and"，前面加 "and" / ","
CollectionHumanizer::oxford(['Michal', 'Norbert', 'Lukasz', 'Pawel'], 2);
// => "Michal, Norbert, and 2 others"

CollectionHumanizer::oxford(['Michal', 'Norbert', 'Lukasz'], 2);
// => "Michal, Norbert, and 1 other"

CollectionHumanizer::oxford(['Michal', 'Norbert']);
// => "Michal and Norbert"

DateTime 差值自然语言

use Coduo\PHPHumanizer\DateTimeHumanizer;

$past   = new \DateTime("2014-04-26 13:00:00");
$future = new \DateTime("2014-04-26 13:00:05");

DateTimeHumanizer::difference($future, $past);   // "5 seconds from now"

$earlier = new \DateTime("2014-04-26 12:59:00");
DateTimeHumanizer::difference($earlier, $past); // "1 minute ago"

// 同一时刻
DateTimeHumanizer::difference($past, $past);     // "just now"

⚠️ DateTimeHumanizer 的语言本地化依赖翻译组件，README 示例以英文为主；中文 zh 支持情况建议实际 composer 安装后测试。

典型适用场景

  1. 后台管理列表页：字段名 created_at → 列标题 Created At
  2. 文件大小展示：API 返回字节数，前端显示 "2.5 GB" 而非 "2684354560"
  3. 数据排名展示："第 23 位" → 列表排序显示"23rd"`
  4. 博客/文章截断：保留 HTML 标签的摘要截断，不用担心标签残缺
  5. 多语言数字格式化：波兰语、荷兰语等不同 locale 的数字格式自动处理

坑与注意

  1. 中文支持未验证：README 演示以英文为主，ordinalize 虽支持 locale 参数（如 nl 荷兰语），但中文 zh 完整度未知，建议测试后再上生产
  2. truncate 行为按字符数截断：如果截断位置正好在单词中间会寻找最近的完整单词作为截断点，但如果文本本身极短（如 2 个字符）截断结果可能是一个单字符
  3. HTML 截断白名单标签需要自行维护：如果新版本引入了新的语义化标签（如 <article>、<time>），需要同步更新白名单
  4. binarySuffix(1) 返回 "1 bytes"：这是官方行为（而非 "1 byte"），非 bug，但展示层需要注意
  5. 依赖 Composer autoload：不要直接 include 单文件，需走 vendor/autoload.php
  6. PHP 8.x 新增 typed properties：如果用旧版 PHP（< 8.1）需确认 coduo/php-humanizer 的版本要求；README 标注 5.x 要求 PHP >= 8.1

与同类对比

库 语言 字段 humanize 数字 日期差值 HTML 截断
coduo/php-humanizer PHP ✅ ✅ ordinal / Roman / binary / metric ✅ ✅
venture/喉 PHP ❌ 仅有 ordinal ❌ ❌
kylekatarnls/humanizer PHP ❌ ✅ ordinal / Roman ✅ ❌
Laravel 辅助函数 PHP ✅（Str::headline） 部分 ✅ ❌

php-humanizer 的优势在于功能覆盖面广，一个库解决字符串、数值、集合、日期四类 humanize 需求；如果你的项目已经重度依赖 Laravel，Str::headline 可以覆盖部分字符串 humanize 场景，但 ordinalize 和 HTML 截断仍是 php-humanizer 独有一套。

一句话推荐结论

php-humanizer 是一个「瑞士军刀」型 PHP 辅助库——字段名美化、数字格式化、HTML 安全截断、牛津列表，这些前端展示层的脏活它一站式搞定；不过使用前请确认 PHP 版本（>= 8.1）和中文 locale 的实际覆盖情况，小项目或 Laravel 项目可以先看看框架自带函数是否够用。

  • 原始 README：https://github.com/coduo/php-humanizer
  • Packagist：https://packagist.org/packages/coduo/php-humanizer
  • 5.x 分支 README：https://github.com/coduo/php-humanizer/tree/5.x/README.md