🇨🇳 基于 mozillazg/pinyin-data 词典的中文转拼音工具，更准确的支持多音字的汉字转拼音解决方案。
- 准确的多音字支持
- 多种拼音风格（声调符号、数字声调、无声调）
- 支持姓氏识别
- 灵活的性能优化策略
- 内存友好的设计
- 完善的测试覆盖
使用 Composer 安装:
composer require overtrue/pinyin:^6.0除了获取首字母的方法外，所有方法都支持第二个参数，用于指定拼音的格式，可选值为：
symbol（默认）声调符号，例如pīn yīnnone不输出声调，例如pin yinnumber末尾数字模式的拼音，例如pin1 yin1
你可以使用字符串值或者 ToneStyle 枚举：
use Overtrue\Pinyin\Pinyin;
use Overtrue\Pinyin\ToneStyle;
// 使用字符串
echo Pinyin::sentence('你好', 'none'); // ni hao
echo Pinyin::sentence('你好', 'number'); // ni3 hao3
echo Pinyin::sentence('你好', 'symbol'); // nǐ hǎo
// 使用枚举（推荐）
echo Pinyin::sentence('你好', ToneStyle::NONE); // ni hao
echo Pinyin::sentence('你好', ToneStyle::NUMBER); // ni3 hao3
echo Pinyin::sentence('你好', ToneStyle::SYMBOL); // nǐ hǎo除了 permalink 返回字符串外，其它方法都返回集合类型 Overtrue\Pinyin\Collection：
use Overtrue\Pinyin\Pinyin;
$pinyin = Pinyin::sentence('你好，世界');你可以通过以下方式访问集合内容:
echo $pinyin; // nǐ hǎo shì jiè
// 直接将对象转成字符串
$string = (string) $pinyin; // nǐ hǎo shì jiè
$pinyin->toArray(); // ['nǐ', 'hǎo', 'shì', 'jiè']
// 直接使用索引访问
$pinyin[0]; // 'nǐ'
// 使用函数遍历
$pinyin->map('ucfirst'); // ['Nǐ', 'Hǎo', 'Shì', 'Jiè']
// 拼接为字符串
$pinyin->join(' '); // 'nǐ hǎo shì jiè'
$pinyin->join('-'); // 'nǐ-hǎo-shì-jiè'
// 转成 json
$pinyin->toJson(); // '["nǐ","hǎo","shì","jiè"]'
json_encode($pinyin); // '["nǐ","hǎo","shì","jiè"]'use Overtrue\Pinyin\Pinyin;
use Overtrue\Pinyin\ToneStyle;
echo Pinyin::sentence('带着希望去旅行，比到达终点更美好');
// dài zhe xī wàng qù lǚ xíng ， bǐ dào dá zhōng diǎn gèng měi hǎo
// 去除声调
echo Pinyin::sentence('带着希望去旅行，比到达终点更美好', ToneStyle::NONE);
// dai zhe xi wang qu lv xing ， bi dao da zhong dian geng mei hao
// 保留所有非汉字字符
echo Pinyin::fullSentence('ル是片假名，π是希腊字母', ToneStyle::NONE);
// ル shi pian jia ming ，π shi xi la zi mu通常用于文章链接等，可以使用 permalink 方法获取拼音字符串：
echo Pinyin::permalink('带着希望去旅行'); // dai-zhe-xi-wang-qu-lyu-xing
echo Pinyin::permalink('带着希望去旅行', '.'); // dai.zhe.xi.wang.qu.lyu.xing通常用于创建搜索用的索引，可以使用 abbr 方法转换：
Pinyin::abbr('带着希望去旅行'); // ['d', 'z', 'x', 'w', 'q', 'l', 'x']
echo Pinyin::abbr('带着希望去旅行')->join('-'); // d-z-x-w-q-l-x
echo Pinyin::abbr('你好2018！')->join(''); // nh2018
echo Pinyin::abbr('Happy New Year! 2018！')->join(''); // HNY2018
// 保留原字符串的英文单词
echo Pinyin::abbr('CGV电影院', false, true)->join(''); // CGVdyy姓名首字母
将首字作为姓氏转换，其余作为普通词语转换：
Pinyin::nameAbbr('欧阳'); // ['o', 'y']
echo Pinyin::nameAbbr('单单单')->join('-'); // s-d-d姓名的姓的读音有些与普通字不一样，比如 ‘单’ 常见的音为 dan，而作为姓的时候读 shan。
Pinyin::name('单某某'); // ['shàn', 'mǒu', 'mǒu']
Pinyin::name('单某某', 'none'); // ['shan', 'mou', 'mou']
Pinyin::name('单某某', 'none')->join('-'); // shan-mou-mou根据国家规定 关于中国护照旅行证上姓名拼音 ü（吕、律、闾、绿、女等）统一拼写为 YU 的提醒 的规则，将 ü 转换为 yu：
Pinyin::passportName('吕小布'); // ['lyu', 'xiao', 'bu']
Pinyin::passportName('女小花'); // ['nyu', 'xiao', 'hua']
Pinyin::passportName('律师'); // ['lyu', 'shi']多音字的返回值为关联数组的集合，默认返回去重后的所有读音：
$pinyin = Pinyin::heteronym('重庆');
$pinyin['重']; // ["zhòng", "chóng", "tóng"]
$pinyin['庆']; // ["qìng"]
$pinyin->toArray();
// [
// "重": ["zhòng", "chóng", "tóng"],
// "庆": ["qìng"]
// ]如果不想要去重，可以数组形式返回：
$pinyin = Pinyin::heteronym('重庆重庆', ToneStyle::SYMBOL, true);
// or
$pinyin = Pinyin::heteronymAsList('重庆重庆', ToneStyle::SYMBOL);
$pinyin->toArray();
// [
// ["重" => ["zhòng", "chóng", "tóng"]],
// ["庆" => ["qìng"]],
// ["重" => ["zhòng", "chóng", "tóng"]],
// ["庆" => ["qìng"]]
// ]和多音字类似，单字的返回值为字符串，多音字将根据该字字频调整得到常用音：
$pinyin = Pinyin::chars('重庆');
echo $pinyin['重']; // "zhòng"
echo $pinyin['庆']; // "qìng"
$pinyin->toArray();
// [
// "重": "zhòng",
// "庆": "qìng"
// ]Warning
当单字处理时由于多音字来自词频表中取得常用音，所以在词语环境下可能出现不正确的情况，建议使用多音字处理。
v6.0+ 版本提供了三种不同的转换策略，以适应不同的使用场景：
- 内存占用：~400KB
- 适用场景：Web 请求、内存受限环境
- 特点：每次加载一个词典段，用完即释放
use Overtrue\Pinyin\Pinyin;
// 使用内存优化策略（默认）
Pinyin::useMemoryOptimized();
$result = Pinyin::sentence('你好世界');
echo $result; // nǐ hǎo shì jiè- 内存占用：~4MB
- 适用场景：批处理、长时运行进程
- 特点：缓存所有词典数据，重复转换速度提升 2-3 倍
// 使用缓存策略
Pinyin::useCached();
// 批量处理时性能更好
foreach ($largeDataset as $text) {
$result = Pinyin::sentence($text);
echo $result . "\n";
}
// 清理缓存（可选）
\Overtrue\Pinyin\Converters\CachedConverter::clearCache();- 内存占用：600KB-1.5MB
- 适用场景：通用场景、自动优化
- 特点：根据文本长度智能选择加载策略
// 使用智能策略
Pinyin::useSmart();
// 短文本自动优化
$result1 = Pinyin::sentence('你好'); // 跳过长词词典
echo $result1; // nǐ hǎo
// 长文本自动调整
$result2 = Pinyin::sentence($longText); // 加载必要的词典
echo $result2;// 根据运行环境自动选择最佳策略
Pinyin::useAutoStrategy();
// 获取推荐策略信息
$recommended = \Overtrue\Pinyin\ConverterFactory::recommend();
echo "推荐策略: {$recommended}";use Overtrue\Pinyin\ConverterFactory;
// 创建特定策略的转换器
$converter = ConverterFactory::make('cached');
$result = $converter->convert('你好世界');
echo $result; // nǐ hǎo shì jiè
// 监控内存使用情况
$initialMemory = memory_get_usage();
$converter->convert('测试文本');
$memoryGrowth = memory_get_usage() - $initialMemory;
echo "内存增长: " . round($memoryGrowth / 1024, 2) . " KB";| 策略 | 内存占用 | 首次转换 | 重复转换 | 推荐场景 |
|---|---|---|---|---|
| Memory Optimized | ~400KB | 中等 | 中等 | Web 请求 |
| Cached | ~4MB | 慢 | 最快 | 批处理 |
| Smart | 600KB-1.5MB | 快 | 快 | 通用场景 |
运行基准测试查看实际性能：
# 运行标准基准测试
php benchmark/run.php
# 详细的策略对比测试
php benchmark/compare-strategies.php根据您的使用场景选择最合适的转换策略：
// 在应用启动时设置
Pinyin::useMemoryOptimized(); // 默认策略，内存占用最小
// 或在 ServiceProvider 中配置
public function boot()
{
Pinyin::useMemoryOptimized();
}// 处理大量数据时使用缓存策略
Pinyin::useCached();
$results = [];
foreach ($thousandsOfTexts as $text) {
$results[] = Pinyin::sentence($text);
}
// 处理完成后清理缓存
\Overtrue\Pinyin\Converters\CachedConverter::clearCache();class ConvertPinyinJob implements ShouldQueue
{
public function handle()
{
// 队列任务中使用智能策略
Pinyin::useSmart();
// 处理任务...
}
}use Overtrue\Pinyin\ConverterFactory;
// 监控不同策略的内存使用情况
$strategies = ['memory', 'cached', 'smart'];
foreach ($strategies as $strategy) {
$converter = ConverterFactory::make($strategy);
$initialMemory = memory_get_usage();
$converter->convert('测试文本');
$memoryGrowth = memory_get_usage() - $initialMemory;
echo "策略: {$strategy}, 内存增长: " . round($memoryGrowth / 1024, 2) . " KB" . PHP_EOL;
}项目提供了多个基准测试工具：
# 运行标准基准测试
php benchmark/run.php
# 详细的策略对比
php benchmark/compare-strategies.php基准测试会显示不同策略的性能对比，包括：
- 内存使用情况
- 转换速度
- 不同文本长度的性能表现
- 生产环境：使用
Memory Optimized策略，避免内存泄漏 - 开发环境：可以使用
Smart策略，平衡性能和内存 - 批处理任务：使用
Cached策略，处理完成后调用clearCache() - 内存受限环境：严格使用
Memory Optimized策略
基于 1000 次转换的基准测试结果：
| 场景 | Memory Optimized | Cached | Smart |
|---|---|---|---|
| 短文本（<10字） | 1.2ms | 0.5ms | 0.8ms |
| 中等文本（10-50字） | 3.5ms | 1.2ms | 2.1ms |
| 长文本（>100字） | 8.7ms | 3.1ms | 5.2ms |
| 内存占用 | 400KB | 4MB | 1.5MB |
💡 提示：缓存策略在重复转换时性能提升约 2-3 倍，但会占用更多内存。
根据国家语言文字工作委员会的规定，lv、lyu、lǚ 都是正确的，但是 lv 是最常用的，所以默认使用 lv，如果你需要使用其他的，可以在初始化时传入：
echo Pinyin::sentence('旅行');
// lǚ xíng
echo Pinyin::sentence('旅行', 'none');
// lv xing
echo Pinyin::yuToYu()->sentence('旅行', 'none');
// lyu xing
echo Pinyin::yuToU()->sentence('旅行', 'none');
// lu xing
echo Pinyin::yuToV()->sentence('旅行', 'none');
// lv xingWarning
仅在拼音风格为非
none模式下有效。
你可以使用命令行来实现拼音的转换：
php ./bin/pinyin 带着希望去旅行 --method=sentence --tone-style=symbol
# dài zhe xī wàng qù lǚ xíng更多使用方法，可以查看帮助文档：
php ./bin/pinyin --help
# Usage:
# ./pinyin [chinese] [method] [options]
# Options:
# -j, --json 输出 JSON 格式.
# -c, --compact 不格式化输出 JSON.
# -m, --method=[method] 转换方式，可选：sentence/fullSentence/permalink/abbr/nameAbbr/name/passportName/phrase/heteronym/chars.
# --no-tone 不使用音调.
# --tone-style=[style] 音调风格，可选值：symbol/none/number, default: none.
# -h, --help 显示帮助.# 基本转换
php ./bin/pinyin "你好世界"
# ni hao shi jie
# 指定音调风格
php ./bin/pinyin "你好世界" --tone-style=symbol
# nǐ hǎo shì jiè
php ./bin/pinyin "你好世界" --tone-style=number
# ni3 hao3 shi4 jie4
# 生成链接格式
php ./bin/pinyin "带着希望去旅行" --method=permalink
# dai-zhe-xi-wang-qu-lv-xing
# 获取首字母
php ./bin/pinyin "带着希望去旅行" --method=abbr
# d z x w q l x
# 多音字转换（JSON格式）
php ./bin/pinyin "重庆" --method=heteronym --json
# {"重":["zhong","chong","tong"],"庆":["qing"]}
# 姓名转换
php ./bin/pinyin "欧阳修" --method=name
# ou yang xiu独立的包在这里：overtrue/laravel-pinyin
如何你有这个需求，也可以了解我的另一个包：overtrue/php-opencc
欢迎提意见及完善补充词库：
- 单字拼音错误请添加到：sources/pathes/chars.txt；
- 词语错误或补齐，请添加到：sources/pathes/words.txt；
如果你喜欢我的项目并想支持它，点击这里 ❤️
想知道如何从零开始构建 PHP 扩展包？
请关注我的实战课程，我会在此课程中分享一些扩展开发经验 —— 《PHP 扩展包实战教程 - 从入门到发布》
MIT