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://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)

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

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

## 特性

- 准确的多音字支持
- 多种拼音风格（声调符号、数字声调、无声调）
- 支持姓氏识别
- 灵活的性能优化策略
- 内存友好的设计
- 完善的测试覆盖

## 安装

使用 Composer 安装:

```bash
composer require overtrue/pinyin:^6.0
```

## 使用

### 拼音风格

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

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

你可以使用字符串值或者 `ToneStyle` 枚举：

```php
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`](https://github.com/overtrue/pinyin/blob/master/src/Collection.php)：

```php
use Overtrue\Pinyin\Pinyin;

$pinyin = Pinyin::sentence('你好，世界');
```

你可以通过以下方式访问集合内容:

```php
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è"]'
```

### 文字段落转拼音

```php
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` 方法获取拼音字符串：

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

### 获取首字符字符串

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

```php
Piny