一、前置准备：安装
overtrue/pinyin是 PHP 生态中非常流行的汉字转拼音扩展包，支持多种拼音格式、多音字处理、简繁转换等功能。使用前需先安装。
安装方式：
# Composer 安装（推荐） composer require overtrue/pinyin- 安装完成后，直接通过命名空间引入即可使用。
- 支持 Laravel/Lumen 框架便捷集成，也可在原生 PHP 中使用，无需额外配置。
二、核心参数说明
overtrue/pinyin 的核心为 Pinyin 类。其配置和用法主要分为以下三部分：
1. 实例化配置参数（可选）
实例化 Overtrue\Pinyin\Pinyin 时，可传入关联数组作为配置：
参数名 | 类型 | 默认值 | 说明 |
delimiter | string | ''（空字符串） | 拼音分隔符，如'-'结果为zhong-guo |
accent | bool | false | 是否保留拼音声调（如zhōng） |
upper | bool | false | 是否转为全大写 |
lower | bool | true | 是否转为全小写（upper为true时失效） |
keep_unconvertible | bool | false | 是否保留无法转换的字符（如特殊符号、外文） |
mode | int | Pinyin::NORMAL | 拼音转换模式，详见下文 |
2. 核心转换模式（mode参数）
- Pinyin::NORMAL（默认）：普通模式，不处理多音字，返回第一个常见读音。速度最快，内存占用最低。
- Pinyin::TONE：声调模式，返回带声调拼音（配合 accent=true 效果更完整），支持多音字声调标注。
- Pinyin::POLYPHONE：多音字模式，返回所有可能读音（以数组形式存储），适合需要精准处理多音字的场景。
3. 核心方法运行时参数
以常用的 convert() 方法为例：
// 方法签名 public function convert(string $string, int $mode = null, bool $keepUnconvertible = null): array- $string：必填，待转换的汉字字符串
- $mode：可选，覆盖实例化时的 mode 配置，优先级更高
- $keepUnconvertible：可选，覆盖实例化时的 keep_unconvertible 配置
其他常用方法（如 permalink()、abbr()）参数类似，均可覆盖实例化配置。
三、实用使用示例
示例 1：原生 PHP 基础使用（普通模式，无声调）
<?php require __DIR__ . '/vendor/autoload.php'; use Overtrue\Pinyin\Pinyin; // 实例化（默认配置：无分隔符、无声调、小写、过滤无法转换字符） $pinyin = new Pinyin(); $text = "中国加油，世界和平！"; $result1 = $pinyin->convert($text); print_r($result1); // 输出：Array ( [0] => zhong [1] => guo [2] => jia [3] => you [4] => shi [5] => jie [6] => he [7] => ping ) $result2 = $pinyin->permalink($text); echo $result2 . PHP_EOL; // 输出：zhong-guo-jia-you-shi-jie-he-ping $result3 = $pinyin->abbr($text); echo $result3 . PHP_EOL; // 输出：ZGJYSJHP示例 2：带声调、自定义分隔符（声调模式）
<?php require __DIR__ . '/vendor/autoload.php'; use Overtrue\Pinyin\Pinyin; // 配置：带声调、分隔符为空格、保留无法转换字符 $pinyin = new Pinyin([ 'delimiter' => ' ', 'accent' => true, 'keep_unconvertible' => true, 'mode' => Pinyin::TONE, ]); $text = "重庆（Chongqing）的火锅很好吃！"; $result1 = $pinyin->convert($text); print_r($result1); // 输出：Array ( [0] => chóng [1] => qìng [2] => （ [3] => Chongqing [4] => ） [5] => de [6] => huǒ [7] => guō [8] => hěn [9] => hǎo [10] => chī ) $result2 = $pinyin->permalink($text, '-'); echo $result2 . PHP_EOL; // 输出：chóng-qìng-（-Chongqing-）-de-huǒ-guō-hěn-hǎo-chī示例 3：多音字处理（多音字模式）
<?php require __DIR__ . '/vendor/autoload.php'; use Overtrue\Pinyin\Pinyin; $pinyin = new Pinyin([ 'accent' => true, 'mode' => Pinyin::POLYPHONE, ]); // 多音字："行"、"乐" $text = "行万里路，读万卷书；知足常乐。"; $result = $pinyin->convert($text); print_r($result); // 输出关键部分： // [0] => Array ( [0] => xíng [1] => háng [2] => hàng [3] => xìng ) （"行"的所有读音） // [10] => Array ( [0] => lè [1] => yuè ) （"乐"的所有读音）四、优缺点总结
优点
- 使用便捷：Composer 一键安装，原生 PHP 和 Laravel/Lumen 框架均友好支持，门面、辅助函数等便捷用法。
- 功能完善：支持无声调、带声调、多音字三种核心模式，输出格式丰富，支持简繁转换、特殊字符过滤/保留。
- 性能优秀：底层词库映射，普通模式下速度快、内存占用低，适合高并发场景（如文章标题转拼音、URL 优化等）。
- 维护活跃：主流扩展包，更新及时，兼容 PHP 7.4+ 及 8.x，bug 修复响应快。
- 配置灵活：实例化与运行时参数可灵活切换，满足多样化需求。
缺点
- 多音字处理有限制：多音字模式仅返回所有可能读音，无法自动根据上下文判断正确读音（如“行”在不同语境下读音不同，需开发者自处理）。
- 依赖 Composer：仅支持 Composer 安装和自动加载，非 Composer 项目集成较为繁琐。
- 无生僻字支持：非常见生僻字超出词库范围时无法转换，词库更新略滞后于生僻字使用场景。
- 不支持其他语言：仅支持汉字转拼音，不支持日语、韩语等其他东亚文字的拼音/读音转换。
五、核心汇总
- overtrue/pinyin是 PHP 汉字转拼音的首选扩展包，核心优势在于便捷、高效、功能完善，适合绝大多数业务场景（如 URL 优化、数据检索、拼音排序）。
- 核心关键在于转换模式（普通/声调/多音字）和配置参数（分隔符、声调、大小写），灵活搭配可满足不同输出需求。
- 最大局限是无法上下文区分多音字和不支持生僻字，复杂精准拼音场景需结合业务逻辑补充处理。
- 适用场景：网站文章标题转拼音 URL、用户姓名拼音检索、数据列表拼音排序。
- 不适用场景：古籍生僻字转换、需上下文精准区分多音字的专业文本处理。
