PHP 汉字转拼音扩展包：overtrue/pinyin 全面指南

一、前置准备：安装

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、用户姓名拼音检索、数据列表拼音排序。
• 不适用场景：古籍生僻字转换、需上下文精准区分多音字的专业文本处理。

---