Using overtrue/pinyin in PHP to Convert Chinese Characters to Pinyin

Installation

Install the overtrue/pinyin package via Composer:

composer require overtrue/pinyin

The library’s source code is hosted at https://github.com/overtrue/pinyin .

Basic Usage

The library provides several methods; all accept an optional second parameter to specify the tone format. Available formats are:

symbol  (default) – tone marks, e.g., pīn yīn

none    – no tones, e.g., pin yin

number  – numeric tone suffix, e.g., pin1 yin1

1. Convert a Chinese sentence to a pinyin array

use Overtrue\Pinyin\Pinyin;

$pinyin = Pinyin::sentence('你好，世界'); // 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è'

$pinyin->toJson(); // '["nǐ","hǎo","shì","jiè"]'

json_encode($pinyin); // '["nǐ","hǎo","shì","jiè"]'

2. Convert a paragraph of text

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

3. Generate a URL‑friendly pinyin string

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

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

4. Get the initials of a phrase

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

5. Get name initials

echo Pinyin::nameAbbr('欧阳'); // o y

echo Pinyin::nameAbbr('单单单')->join('-'); // s-d-d

6. Handle polyphones (characters with multiple pronunciations)

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

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

$pinyin['庆']; // ["qìng"]

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

7. Command‑line tool

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

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

8. Additional options

php ./bin/pinyin --help

# Usage:

#     ./pinyin [chinese] [method] [options]

# Options:

#     -j, --json               Output JSON format.

#     -c, --compact            Compact JSON output.

#     -m, --method=[method]    Conversion method, e.g., name/phrase/permalink/polyphones/chars/nameAbbr/abbr/sentence.

#     --no-tone                Disable tones.

#     --tone-style=[style]     Tone style: default/none/number.

#     -h, --help               Show help.

For more examples, refer to the library’s documentation.