{"id":13536365,"url":"https://github.com/overtrue/pinyin","last_synced_at":"2026-03-06T15:03:51.866Z","repository":{"id":18674014,"uuid":"21882528","full_name":"overtrue/pinyin","owner":"overtrue","description":"🇨🇳 基于词库的中文转拼音优质解决方案","archived":false,"fork":false,"pushed_at":"2025-03-16T02:18:10.000Z","size":23697,"stargazers_count":4373,"open_issues_count":0,"forks_count":770,"subscribers_count":148,"default_branch":"master","last_synced_at":"2025-04-30T02:39:27.115Z","etag":null,"topics":["php","pinyin"],"latest_commit_sha":null,"homepage":"https://github.com/overtrue/pinyin","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/overtrue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["overtrue"]}},"created_at":"2014-07-16T01:49:23.000Z","updated_at":"2025-04-26T21:13:55.000Z","dependencies_parsed_at":"2024-03-30T04:32:42.024Z","dependency_job_id":"a341877c-4b9a-48f7-aeed-b1cd09f8e748","html_url":"https://github.com/overtrue/pinyin","commit_stats":{"total_commits":347,"total_committers":34,"mean_commits":"10.205882352941176","dds":"0.12680115273775217","last_synced_commit":"cd40f248239231ae2d1f94348c323a40c7fc58b1"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overtrue%2Fpinyin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overtrue%2Fpinyin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overtrue%2Fpinyin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overtrue%2Fpinyin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/overtrue","download_url":"https://codeload.github.com/overtrue/pinyin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251837055,"owners_count":21651754,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php","pinyin"],"created_at":"2024-08-01T09:00:37.822Z","updated_at":"2025-05-05T22:45:28.240Z","avatar_url":"https://github.com/overtrue.png","language":"PHP","funding_links":["https://github.com/sponsors/overtrue"],"categories":["目录","PHP","其他( Miscellaneous )","类库"],"sub_categories":["字符串 Strings","未归类"],"readme":"# Pinyin\n\n[![Test](https://github.com/overtrue/pinyin/actions/workflows/test.yml/badge.svg)](https://github.com/overtrue/pinyin/actions/workflows/test.yml)\n[![Latest Stable Version](https://poser.pugx.org/overtrue/pinyin/v/stable.svg)](https://packagist.org/packages/overtrue/pinyin) [![Total Downloads](https://poser.pugx.org/overtrue/pinyin/downloads.svg)](https://packagist.org/packages/overtrue/pinyin) [![Latest Unstable Version](https://poser.pugx.org/overtrue/pinyin/v/unstable.svg)](https://packagist.org/packages/overtrue/pinyin) [![License](https://poser.pugx.org/overtrue/pinyin/license.svg)](https://packagist.org/packages/overtrue/pinyin)\n\n:cn: 基于 [mozillazg/pinyin-data](https://github.com/mozillazg/pinyin-data) 词典的中文转拼音工具，更准确的支持多音字的汉字转拼音解决方案。\n\n[喜欢我的项目？点击这里支持我](https://github.com/sponsors/overtrue)\n\n## 安装\n\n使用 Composer 安装:\n\n```bash\ncomposer require overtrue/pinyin:^5.0\n```\n\n## 使用\n\n### 拼音风格\n\n除了获取首字母的方法外，所有方法都支持第二个参数，用于指定拼音的格式，可选值为：\n\n- `symbol` （默认）声调符号，例如 `pīn yīn`\n- `none` 不输出拼音，例如 `pin yin`\n- `number` 末尾数字模式的拼音，例如 `pin1 yin1`\n\n### 返回值\n\n除了 `permalink` 返回字符串外，其它方法都返回集合类型 [`Overtrue\\Pinyin\\Collection`](https://github.com/overtrue/pinyin/blob/master/src/Collection.php)：\n\n```php\nuse Overtrue\\Pinyin\\Pinyin;\n\n$pinyin = Pinyin::sentence('你好，世界');\n```\n\n你可以通过以下方式访问集合内容:\n\n```php\necho $pinyin; // nǐ hǎo shì jiè\n\n// 直接将对象转成字符串\n$string = (string) $pinyin; // nǐ hǎo shì jiè\n\n$pinyin-\u003etoArray(); // ['nǐ', 'hǎo', 'shì', 'jiè']\n\n// 直接使用索引访问\n$pinyin[0]; // 'nǐ'\n\n// 使用函数遍历\n$pinyin-\u003emap('ucfirst'); // ['Nǐ', 'Hǎo', 'Shì', 'Jiè']\n\n// 拼接为字符串\n$pinyin-\u003ejoin(' '); // 'nǐ hǎo shì jiè'\n$pinyin-\u003ejoin('-'); // 'nǐ-hǎo-shì-jiè'\n\n// 转成 json\n$pinyin-\u003etoJson(); // '[\"nǐ\",\"hǎo\",\"shì\",\"jiè\"]'\njson_encode($pinyin); // '[\"nǐ\",\"hǎo\",\"shì\",\"jiè\"]'\n```\n\n### 文字段落转拼音\n\n```php\nuse Overtrue\\Pinyin\\Pinyin;\n\necho Pinyin::sentence('带着希望去旅行，比到达终点更美好');\n// dài zhe xī wàng qù lǚ xíng ， bǐ dào dá zhōng diǎn gèng měi hǎo\n\n// 去除声调\necho Pinyin::sentence('带着希望去旅行，比到达终点更美好', 'none');\n// dai zhe xi wang qu lv xing ， bi dao da zhong dian geng mei hao\n\n// 保留所有非汉字字符\necho Pinyin::fullSentence('ル是片假名，π是希腊字母', 'none');\n// ル shi pian jia ming ，π shi xi la zi mu\n```\n\n### 生成用于链接的拼音字符串\n\n通常用于文章链接等，可以使用 `permalink` 方法获取拼音字符串：\n\n```php\necho Pinyin::permalink('带着希望去旅行'); // dai-zhe-xi-wang-qu-lyu-xing\necho Pinyin::permalink('带着希望去旅行', '.'); // dai.zhe.xi.wang.qu.lyu.xing\n```\n\n### 获取首字符字符串\n\n通常用于创建搜索用的索引，可以使用 `abbr` 方法转换：\n\n```php\nPinyin::abbr('带着希望去旅行'); // ['d', 'z', 'x', 'w', 'q', 'l', 'x']\necho Pinyin::abbr('带着希望去旅行')-\u003ejoin('-'); // d-z-x-w-q-l-x\necho Pinyin::abbr('你好2018！')-\u003ejoin(''); // nh2018\necho Pinyin::abbr('Happy New Year! 2018！')-\u003ejoin(''); // HNY2018\n\n// 保留原字符串的英文单词\necho Pinyin::abbr('CGV电影院', false, true)-\u003ejoin(''); // CGVdyy\n```\n\n**姓名首字母**\n\n将首字作为姓氏转换，其余作为普通词语转换：\n\n```php\nPinyin::nameAbbr('欧阳'); // ['o', 'y']\necho Pinyin::nameAbbr('单单单')-\u003ejoin('-'); // s-d-d\n```\n\n### 姓名转换\n\n姓名的姓的读音有些与普通字不一样，比如 ‘单’ 常见的音为 `dan`，而作为姓的时候读 `shan`。\n\n```php\nPinyin::name('单某某'); // ['shàn', 'mǒu', 'mǒu']\nPinyin::name('单某某', 'none'); // ['shan', 'mou', 'mou']\nPinyin::name('单某某', 'none')-\u003ejoin('-'); // shan-mou-mou\n```\n\n### 护照姓名转换\n\n根据国家规定 [关于中国护照旅行证上姓名拼音 ü（吕、律、闾、绿、女等）统一拼写为 YU 的提醒](http://sg.china-embassy.gov.cn/lsfw/zghz1/hzzxdt/201501/t20150122_2022198.htm) 的规则，将 `ü` 转换为 `yu`：\n\n```php\nPinyin::passportName('吕小布'); // ['lyu', 'xiao', 'bu']\nPinyin::passportName('女小花'); // ['nyu', 'xiao', 'hua']\nPinyin::passportName('律师'); // ['lyu', 'shi']\n```\n\n### 多音字\n\n多音字的返回值为关联数组的集合，默认返回去重后的所有读音：\n\n```php\n$pinyin = Pinyin::polyphones('重庆');\n\n$pinyin['重']; // [\"zhòng\", \"chóng\", \"tóng\"]\n$pinyin['庆']; // [\"qìng\"]\n\n$pinyin-\u003etoArray();\n// [\n//     \"重\": [\"zhòng\", \"chóng\", \"tóng\"],\n//     \"庆\": [\"qìng\"]\n// ]\n```\n\n如果不想要去重，可以数组形式返回：\n\n```php\n$pinyin = Pinyin::polyphones('重庆重庆', Converter::TONE_STYLE_SYMBOL, true);\n\n// or \n$pinyin = Pinyin::polyphonesAsArray('重庆重庆', Converter::TONE_STYLE_SYMBOL);\n\n$pinyin-\u003etoArray();\n// [\n//     [\"重\" =\u003e [\"zhòng\", \"chóng\", \"tóng\"]],\n//     [\"庆\" =\u003e [\"qìng\"]],\n//     [\"重\" =\u003e [\"zhòng\", \"chóng\", \"tóng\"]],\n//     [\"庆\" =\u003e [\"qìng\"]]\n// ]\n```\n\n### 单字转拼音\n\n和多音字类似，单字的返回值为字符串，多音字将根据该字字频调整得到常用音：\n\n```php\n$pinyin = Pinyin::chars('重庆');\n\necho $pinyin['重']; // \"zhòng\"\necho $pinyin['庆']; // \"qìng\"\n\n$pinyin-\u003etoArray();\n// [\n//     \"重\": \"zhòng\",\n//     \"庆\": \"qìng\"\n// ]\n```\n\n\u003e **Warning**\n\u003e\n\u003e 当单字处理时由于多音字来自词频表中取得常用音，所以在词语环境下可能出现不正确的情况，建议使用多音字处理。\n\n更多使用请参考 [测试用例](https://github.com/overtrue/pinyin/blob/master/tests/PinyinTest.php)。\n\n## v/yu/ü 的问题\n\n根据国家语言文字工作委员会的规定，`lv`、`lyu`、`lǚ` 都是正确的，但是 `lv` 是最常用的，所以默认使用 `lv`，如果你需要使用其他的，可以在初始化时传入：\n\n```php\necho Pinyin::sentence('旅行');\n// lǚ xíng\n\necho Pinyin::sentence('旅行', 'none');\n// lv xing\n\necho Pinyin::yuToYu()-\u003esentence('旅行', 'none');\n// lyu xing\n\necho Pinyin::yuToU()-\u003esentence('旅行', 'none');\n// lu xing\n\necho Pinyin::yuToV()-\u003esentence('旅行', 'none');\n// lv xing\n```\n\n\u003e **Warning**\n\u003e\n\u003e 仅在拼音风格为非 `none` 模式下有效。\n\n## 命令行工具\n\n你可以使用命令行来实现拼音的转换：\n\n```bash\nphp ./bin/pinyin 带着希望去旅行 --method=sentence --tone-style=symbol\n# dài zhe xī wàng qù lǚ xíng\n```\n\n更多使用方法，可以查看帮助文档：\n\n```bash\nphp ./bin/pinyin --help\n\n# Usage:\n#     ./pinyin [chinese] [method] [options]\n# Options:\n#     -j, --json               输出 JSON 格式.\n#     -c, --compact            不格式化输出 JSON.\n#     -m, --method=[method]    转换方式，可选：sentence/sentenceFull/permalink/abbr/nameAbbr/name/passportName/phrase/polyphones/chars.\n#     --no-tone                不使用音调.\n#     --tone-style=[style]     音调风格，可选值：symbol/none/number, default: none.\n#     -h, --help               显示帮助.\n```\n\n## 在 Laravel 中使用\n\n独立的包在这里：[overtrue/laravel-pinyin](https://github.com/overtrue/laravel-pinyin)\n\n## 中文简繁转换\n\n如何你有这个需求，也可以了解我的另一个包：[overtrue/php-opencc](https://github.com/overtrue/php-opencc)\n\n## Contribution\n\n欢迎提意见及完善补充词库：\n\n- 单字拼音错误请添加到：[sources/pathes/chars.txt](https://github.com/overtrue/pinyin/blob/master/sources/pathes/chars.txt)；\n- 词语错误或补齐，请添加到：[sources/pathes/words.txt](https://github.com/overtrue/pinyin/blob/master/sources/pathes/words.txt)；\n\n## 参考\n\n- [mozillazg/pinyin-data](https://github.com/mozillazg/pinyin-data)\n- [详细参考资料](https://github.com/overtrue/pinyin-resources)\n\n## :heart: Sponsor me\n\n[![Sponsor me](https://github.com/overtrue/overtrue/blob/master/sponsor-me.svg?raw=true)](https://github.com/sponsors/overtrue)\n\n如果你喜欢我的项目并想支持它，[点击这里 :heart:](https://github.com/sponsors/overtrue)\n\n## Project supported by JetBrains\n\nMany thanks to Jetbrains for kindly providing a license for me to work on this and other open-source projects.\n\n[![](https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.svg)](https://www.jetbrains.com/?from=https://github.com/overtrue)\n\n## PHP 扩展包开发\n\n\u003e 想知道如何从零开始构建 PHP 扩展包？\n\u003e\n\u003e 请关注我的实战课程，我会在此课程中分享一些扩展开发经验 —— [《PHP 扩展包实战教程 - 从入门到发布》](https://learnku.com/courses/creating-package)\n\n# License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fovertrue%2Fpinyin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fovertrue%2Fpinyin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fovertrue%2Fpinyin/lists"}