PHPackages                             linfly/pinyin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. linfly/pinyin

ActiveLibrary[Utility & Helpers](/categories/utility)

linfly/pinyin
=============

Chinese to pinyin translator.

5.0.3(3y ago)07MITPHPPHP >=8.0.2

Since Jul 16Pushed 3y agoCompare

[ Source](https://github.com/imlinfly/pinyin-fork)[ Packagist](https://packagist.org/packages/linfly/pinyin)[ Docs](https://github.com/overtrue/pinyin)[ GitHub Sponsors](https://github.com/overtrue)[ RSS](/packages/linfly-pinyin/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (50)Used By (0)

Pinyin
======

[](#pinyin)

[![Test](https://github.com/overtrue/pinyin/actions/workflows/test.yml/badge.svg)](https://github.com/overtrue/pinyin/actions/workflows/test.yml)[![Latest Stable Version](https://camo.githubusercontent.com/10cbf8c470851ad0bebd058635ad6a781608dfc585994e7837e6578735bf8bb0/68747470733a2f2f706f7365722e707567782e6f72672f6f766572747275652f70696e79696e2f762f737461626c652e737667)](https://packagist.org/packages/overtrue/pinyin) [![Total Downloads](https://camo.githubusercontent.com/7a1ba91c5227ad10249bc6b1c7ca4d01a91e4151b8c6148e02594049132fe200/68747470733a2f2f706f7365722e707567782e6f72672f6f766572747275652f70696e79696e2f646f776e6c6f6164732e737667)](https://packagist.org/packages/overtrue/pinyin) [![Latest Unstable Version](https://camo.githubusercontent.com/33da35dba8b7f80211bb8dec99ae1d4feec1dc089a0c2f653dcad00c58f49c1a/68747470733a2f2f706f7365722e707567782e6f72672f6f766572747275652f70696e79696e2f762f756e737461626c652e737667)](https://packagist.org/packages/overtrue/pinyin) [![License](https://camo.githubusercontent.com/b66704519178e7ac6e1749812b75fcb59d56d65e2510f866b968d8a27ce23846/68747470733a2f2f706f7365722e707567782e6f72672f6f766572747275652f70696e79696e2f6c6963656e73652e737667)](https://packagist.org/packages/overtrue/pinyin)

🇨🇳 基于 [mozillazg/pinyin-data](https://github.com/mozillazg/pinyin-data) 词典的中文转拼音工具，更准确的支持多音字的汉字转拼音解决方案。

[喜欢我的项目？点击这里支持我](https://github.com/sponsors/overtrue)

安装
--

[](#安装)

使用 Composer 安装:

```
composer require overtrue/pinyin:^5.0
```

使用
--

[](#使用)

### 拼音风格

[](#拼音风格)

除了获取首字母的方法外，所有方法都支持第二个参数，用于指定拼音的格式，可选值为：

- `symbol` （默认）声调符号，例如 `pīn yīn`
- `none` 不输出拼音，例如 `pin yin`
- `number` 末尾数字模式的拼音，例如 `pin1 yin1`

### 返回值

[](#返回值)

除了 `permalink` 返回字符串外，其它方法都返回集合类型 [`Overtrue\Pinyin\Collection`](https://github.com/overtrue/pinyin/blob/master/src/Collection.php)：

```
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;

echo Pinyin::sentence('带着希望去旅行，比到达终点更美好');
// dài zhe xī wàng qù lyu xíng ， bǐ dào dá zhōng diǎn gèng měi hǎo

// 去除声调
echo Pinyin::sentence('带着希望去旅行，比到达终点更美好', 'none');
// dai zhe xi wang qu lyu xing ， bi dao da zhong dian geng mei hao
```

### 生成用于链接的拼音字符串

[](#生成用于链接的拼音字符串)

通常用于文章链接等，可以使用 `permalink` 方法获取拼音字符串：

```
echo Pinyin::permalink('带着希望去旅行'); // dai-zhe-xi-wang-qu-lyu-xing
echo Pinyin::permalink('带着希望去旅行', '.'); // dai.zhe.xi.wang.qu.lyu.xing
```

### 获取首字符字符串

[](#获取首字符字符串)

通常用于创建搜索用的索引，可以使用 `abbr` 方法转换：

```
echo 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::nameAbbr('欧阳'); // o y
echo Pinyin::nameAbbr('单单单')->join('-'); // s-d-d
```

### 姓名转换

[](#姓名转换)

姓名的姓的读音有些与普通字不一样，比如 ‘单’ 常见的音为 `dan`，而作为姓的时候读 `shan`。

```
echo Pinyin::name('单某某'); // shàn mǒu mǒu
echo Pinyin::name('单某某', 'none'); // shan mou mou
echo Pinyin::name('单某某', 'none')->join('-'); // shan-mou-mou
```

### 多音字

[](#多音字)

多音字的返回值为关联数组的集合：

```
$pinyin = Pinyin::polyphones('重庆');

$pinyin['重']; // ["zhòng", "chóng", "tóng"]
$pinyin['庆']; // ["qìng"]

$pinyin->toArray();
// [
//     "重": ["zhòng", "chóng", "tóng"],
//     "庆": ["qìng"]
// ]
```

### 单字转拼音

[](#单字转拼音)

和多音字类似，单字的返回值为字符串，多音字将根据该字字频调整得到常用音：

```
$pinyin = Pinyin::polyphones('重庆');

echo $pinyin['重']; // "zhòng"
echo $pinyin['庆']; // "qìng"

$pinyin->toArray();
// [
//     "重": "zhòng",
//     "庆": "qìng"
// ]
```

> **Warning**
>
> 当单字处理时由于多音字来自词频表中取得常用音，所以在词语环境下可能出现不正确的情况，建议使用多音字处理。

更多使用请参考 [测试用例](https://github.com/overtrue/pinyin/blob/master/tests/PinyinTest.php)。

命令行工具
-----

[](#命令行工具)

你可以使用命令行来实现拼音的转换：

```
php ./bin/pinyin 带着希望去旅行

# dài zhe xī wàng qù lyu xíng
```

更多使用方法，可以查看帮助文档：

```
php ./bin/pinyin --help

# Usage:
#     ./pinyin [chinese] [method] [options]
# Options:
#     -j, --json               输出 JSON 格式.
#     -c, --compact            不格式化输出 JSON.
#     -m, --method=[method]    转换方式，可选：name/phrase/permalink/polyphones/chars/nameAbbr/abbr/sentence.
#     --no-tone                不使用音调.
#     --tone-style=[style]     音调风格，可选值：default/none/number.
#     -h, --help               显示帮助.
```

在 Laravel 中使用
-------------

[](#在-laravel-中使用)

独立的包在这里：[overtrue/laravel-pinyin](https://github.com/overtrue/laravel-pinyin)

Contribution
------------

[](#contribution)

欢迎提意见及完善补充词库：

- 单字拼音错误请添加到：[sources/pathes/chars.txt](https://github.com/overtrue/pinyin/blob/master/sources/pathes/chars.txt)；
- 词语错误或补齐，请添加到：[sources/pathes/words.txt](https://github.com/overtrue/pinyin/blob/master/sources/pathes/words.txt)；

参考
--

[](#参考)

- [mozillazg/pinyin-data](https://github.com/mozillazg/pinyin-data)
- [详细参考资料](https://github.com/overtrue/pinyin-resources)

❤️ Sponsor me
-------------

[](#heart-sponsor-me)

[![Sponsor me](https://github.com/overtrue/overtrue/raw/master/sponsor-me.svg?raw=true)](https://github.com/sponsors/overtrue)

如果你喜欢我的项目并想支持它，[点击这里 ❤️](https://github.com/sponsors/overtrue)

Project supported by JetBrains
------------------------------

[](#project-supported-by-jetbrains)

Many thanks to Jetbrains for kindly providing a license for me to work on this and other open-source projects.

[![](https://camo.githubusercontent.com/3cf726e7cdadba47755b7f7ea4227945a92a2fa48aadf4a2573140ec6501c989/68747470733a2f2f7265736f75726365732e6a6574627261696e732e636f6d2f73746f726167652f70726f64756374732f636f6d70616e792f6272616e642f6c6f676f732f6a625f6265616d2e737667)](https://www.jetbrains.com/?from=https://github.com/overtrue)

PHP 扩展包开发
---------

[](#php-扩展包开发)

> 想知道如何从零开始构建 PHP 扩展包？
>
> 请关注我的实战课程，我会在此课程中分享一些扩展开发经验 —— [《PHP 扩展包实战教程 - 从入门到发布》](https://learnku.com/courses/creating-package)

License
=======

[](#license)

MIT

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity4

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity81

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 89.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~66 days

Recently: every ~158 days

Total

49

Last Release

1132d ago

Major Versions

1.4 → 2.02014-10-08

2.x-dev → 3.0.02016-04-25

3.x-dev → 4.0.02018-09-20

4.x-dev → 5.0.02022-07-24

PHP version history (5 changes)3.0.1PHP >=5.4.0

3.0.2PHP >=5.3

4.0.1PHP >=5.5

4.0.6PHP >=7.1

5.0.0PHP >=8.0.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/3547ea3eaacfdb9b1bf6fd3d03fde2e1324ae00679d67542d12b126e7019274b?d=identicon)[linfcom](/maintainers/linfcom)

---

Top Contributors

[![overtrue](https://avatars.githubusercontent.com/u/1472352?v=4)](https://github.com/overtrue "overtrue (320 commits)")[![imlinfly](https://avatars.githubusercontent.com/u/45063822?v=4)](https://github.com/imlinfly "imlinfly (4 commits)")[![xjchengo](https://avatars.githubusercontent.com/u/4819996?v=4)](https://github.com/xjchengo "xjchengo (4 commits)")[![medz](https://avatars.githubusercontent.com/u/5564821?v=4)](https://github.com/medz "medz (3 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")[![ROOKIE20570](https://avatars.githubusercontent.com/u/30709033?v=4)](https://github.com/ROOKIE20570 "ROOKIE20570 (2 commits)")[![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)](https://github.com/dependabot-preview[bot] "dependabot-preview[bot] (2 commits)")[![garveen](https://avatars.githubusercontent.com/u/3214266?v=4)](https://github.com/garveen "garveen (1 commits)")[![Honvid](https://avatars.githubusercontent.com/u/8649968?v=4)](https://github.com/Honvid "Honvid (1 commits)")[![isecret](https://avatars.githubusercontent.com/u/15724152?v=4)](https://github.com/isecret "isecret (1 commits)")[![kmvan](https://avatars.githubusercontent.com/u/3839554?v=4)](https://github.com/kmvan "kmvan (1 commits)")[![abrahamgreyson](https://avatars.githubusercontent.com/u/1341308?v=4)](https://github.com/abrahamgreyson "abrahamgreyson (1 commits)")[![luokuncool](https://avatars.githubusercontent.com/u/6022635?v=4)](https://github.com/luokuncool "luokuncool (1 commits)")[![Modilay](https://avatars.githubusercontent.com/u/61842831?v=4)](https://github.com/Modilay "Modilay (1 commits)")[![N0ah](https://avatars.githubusercontent.com/u/1782836?v=4)](https://github.com/N0ah "N0ah (1 commits)")[![shengbinxu](https://avatars.githubusercontent.com/u/3232275?v=4)](https://github.com/shengbinxu "shengbinxu (1 commits)")[![ssynhtn](https://avatars.githubusercontent.com/u/3341499?v=4)](https://github.com/ssynhtn "ssynhtn (1 commits)")[![summerblue](https://avatars.githubusercontent.com/u/324764?v=4)](https://github.com/summerblue "summerblue (1 commits)")[![totoleo](https://avatars.githubusercontent.com/u/4956722?v=4)](https://github.com/totoleo "totoleo (1 commits)")[![wangfenjin](https://avatars.githubusercontent.com/u/4160646?v=4)](https://github.com/wangfenjin "wangfenjin (1 commits)")

---

Tags

PinyinChinesecn2pinyin

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/linfly-pinyin/health.svg)

```
[![Health](https://phpackages.com/badges/linfly-pinyin/health.svg)](https://phpackages.com/packages/linfly-pinyin)
```

###  Alternatives

[overtrue/pinyin

Chinese to pinyin translator.

4.5k6.5M72](/packages/overtrue-pinyin)[zhuzhichao/ip-location-zh

get the ip's location info with Chinese

617212.5k11](/packages/zhuzhichao-ip-location-zh)[overtrue/chinese-calendar

中国农历转换与查询工具

557103.7k4](/packages/overtrue-chinese-calendar)[zhuzhichao/bank-card-info

Get the bank card info

45464.8k](/packages/zhuzhichao-bank-card-info)[douyasi/identity-card

Chinese Identity Card package

17851.4k3](/packages/douyasi-identity-card)[thl/pinyin

Romanization tool for Traditional Chinese

2519.1k](/packages/thl-pinyin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)