laravel-pinyin puts Chinese to pinyin conversion behind four helpers and a facade

A wrapper, and the library underneath doing the work

laravel-pinyin is described as a Chinese to Pinyin translator for Laravel based on overtrue/pinyin. That dependency is the important fact about the project, because the algorithm, the dictionaries and the conversion rules all live there.

What this package adds is the Laravel integration: a service provider, a container binding, a facade and a set of global helper functions. That is a small amount of code, and it is worth being clear about the division of labour, because the README explicitly defers to the underlying library for configuration and use. About overtrue/pinyin specific configuration and use, refer to overtrue/pinyin.

So if you are evaluating whether the conversion is accurate, or which Chinese characters map to which syllables, or how tone sandhi is handled, those questions are answered by a different repository than this one. This package is the Laravel-shaped way to call it.

The primary language is PHP, the licence is MIT, the default branch is master, and the recent releases are 6.1.0 from 2026-04-17, 6.0.0 from 2025-09-09 and 5.2.0 from 2025-02-25. The last push to the repository was on 2026-10-04, and the top level is minimal: a src/ directory, composer.json, an AGENTS.md, a LICENSE and a README.md.

A package this thin has one job, and it does it cleanly. The risk is not in the code here, it is in how the underlying library's behaviour and its update cadence interact with your Laravel version.

Installing it, and the two steps auto-discovery usually handles

The install is a single Composer requirement.

composer require "overtrue/laravel-pinyin:^6.0"

After that there are two registration steps, and the README is clear that auto-discovery will handle these two steps for you. They are the service provider and the facade alias.

The provider goes in the providers section of config/app.php.

'providers' => [
    //...
    Overtrue\LaravelPinyin\ServiceProvider::class,
],

And the alias is optional, as optional, you can use facade.

'aliases' => [
    //...
    'Pinyin' => Overtrue\LaravelPinyin\Facades\Pinyin::class,
],

The provider is the one you actually need, because it binds the instance into the container. The alias is what gives you the static facade calls, and if your application does not use aliases you can skip it and resolve the instance from the container instead.

The version constraint is worth noting. Requiring ^6.0 pins you to the 6.x line of this package, which is the line that introduced the performance strategies, and the underlying overtrue/pinyin 6.0 is what those strategies were added to match.

Four helpers, and what each one actually returns

The API is small and the README lays it out as a table of helper functions and the methods behind them.

The functions are `pinyin()`, `pinyin_abbr()`, `pinyin_permalink` and `pinyin_sentence`. Behind them sit `app('pinyin')->convert()`, `app('pinyin')->abbr()`, `app('pinyin')->permalink()` and `app('pinyin')->sentence()`.

The difference between them is not cosmetic, and it is the thing to get right before you use them.

`convert()` and `abbr()` produce unaccented syllables. The README's example shows pinyin() on a Chinese sentence returning an array of plain syllables such as dai, zhe, xi, wang, and pinyin_abbr() on a shorter phrase returning an initials string like dzxwqlx. So `convert()` gives you per-character syllable arrays and `abbr()` gives you the initials, which is the form you want for a URL slug or a search key where tone and finals are noise.

`permalink()` is the third shape, and the README does not expand on it, so the detail lives in the underlying library.

`sentence()` is the one that keeps the diacritics. The README's example shows the sentence form returning a tone-marked string, with the tones rendered above the vowels. That is the version for display, and it is the only one of the four where the output is not plain ASCII.

The container binding is the way to get at the instance directly, as the README puts it, you can get the instance of Overtrue\Pinyin\Pinyin from app container.

$pinyin = app('pinyin');

So there are three routes to the same object: the four global helpers, the facade, and the container. Pick one and be consistent, because mixing the container instance and the facade is how you end up with two different configuration states in the same request.

The facade, and the one gotcha in the import

The facade usage is where the README includes a warning that is easy to skim and costly to get wrong.

It shows the import line with a comment attached: use Pinyin, which is the Facade class, NOT Overtrue\Pinyin\Pinyin.

That distinction matters because the two classes have the same short name in different namespaces. The facade is the Laravel-facing class that proxies static calls to the bound instance, and the underlying class is the one from the overtrue/pinyin library itself. Importing the library class and calling a static method on it will not work the way you expect, because that class is not the facade and does not implement the facade contract.

The examples then use the facade in both modes.

use Pinyin; // Facade class, NOT Overtrue\Pinyin\Pinyin

And the calls are static, `Pinyin::convert(...)` for the syllable array and `Pinyin::sentence(...)` for the tone-marked string.

The subtle risk here is that the facade and the underlying class share a name and both are reachable through `use` statements, so an IDE autocompleting the wrong import produces an error at runtime rather than a clear static analysis failure. The comment in the README exists because people hit this.

The other point worth internalising is that the facade resolves the instance from the container at call time. That means the strategy you configure applies to facade calls as well as to the container instance, but it also means a strategy change made partway through a request affects subsequent calls.

The four strategies added in 6.0, and the memory they cost

Version 6.0 is the reason this package has a release worth reading the notes for, because it brought the performance strategies from overtrue/pinyin 6.0.

// Memory Optimized (default) - ~400KB memory usage, suitable for web requests
Pinyin::useMemoryOptimized();

// Cached Strategy - ~4MB memory usage, 2-3x faster for repeated conversions
Pinyin::useCached();

// Smart Strategy - 600KB-1.5MB memory usage, adaptive loading
Pinyin::useSmart();

// Auto Strategy - automatically selects the best strategy for your environment
Pinyin::useAutoStrategy();

The four options and their stated costs are in the comments, and they describe a real trade-off. The default is memory optimised, at roughly 400KB, and it is described as suitable for web requests. The cached strategy is the fast one, at about 4MB and 2 to 3 times faster for repeated conversions. The smart strategy sits in between at 600KB to 1.5MB and does adaptive loading. And the auto strategy picks for you based on your environment.

The right choice depends on your request pattern. A controller that converts one title per request is the memory-optimised case, and paying 4MB per request for a cached dictionary to speed up a single conversion would be a poor trade. A command that converts a whole import file, or a queue worker that converts thousands of rows, is the cached case, because the memory is amortised over many conversions and the setup cost is paid once.

The smart strategy is the compromise for code that does not know which it is, and auto is the same idea delegated to the library.

One more method matters for long-running processes.

// Clear cache when needed (useful in long-running processes)
Pinyin::clearCache();

In a queue worker or a long-lived Octane-style process, a cached dictionary stays resident for the life of the worker. clearCache() is the escape hatch for when that resident state needs to be released.

Where laravel-pinyin is the wrong tool

Three cases, and the first is the one that catches people.

If you need display-grade pinyin for every string, note that only the sentence helper keeps the tone marks. The convert, abbr and permalink forms are ASCII. If your user interface is Chinese and you want to show pinyin alongside characters for reading practice, teaching, or a dictionary feature, the default helpers will give you flat syllables and you will need the sentence form with its word-boundary handling, or the underlying library directly.

The second is if your real requirement is not Chinese text. There is a difference between converting Chinese characters to pinyin and sorting or searching by pinyin, and this package is the former. If what you want is a collation that orders Chinese by pronunciation, or an index keyed on pinyin for a search engine, that is a different piece of work, and the pinyin-permalink output may or may not be the key you want.

The third is if you want to avoid the dependency entirely. This package is a thin layer over overtrue/pinyin, and if you are not otherwise using Laravel's container, facades or helpers, requiring overtrue/pinyin directly gives you the same conversions with fewer moving parts. The trade is that you lose the strategy switching that 6.0 added, unless the underlying library exposes the same calls, which it does, since the strategies came from there.

There is also a version-matching consideration to keep an eye on. This package is at 6.1.0 and moves with the underlying library's major versions, so a Laravel application holding an older pinyin library elsewhere in its dependency tree is a dependency resolution problem rather than a code problem. The composer.json in the repository is where that constraint is declared.

One thing the README does not cover is the dictionary update cycle, which is really the underlying library's concern. If your content contains rare characters or names, the accuracy of the conversion depends on the dictionary version in the overtrue/pinyin release you have installed, and nothing in this repository tells you how often that changes.

Editorial conclusion

Adopt laravel-pinyin if your Laravel application needs to convert Chinese text to pinyin for search slugs, URLs or sorting, and you want the helpers wired into the container rather than calling the library directly. Do not adopt it if you need tone-marked pinyin for display, since the convert and abbr helpers produce unaccented syllables and only the sentence helper keeps diacritics. Verify first which strategy you want, because the default is the memory-optimised one at about 400KB and the cached strategy is the faster option at roughly 4MB.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. overtrue/laravel-pinyin on GitHub
4. README
5. Releases