- How do I install overtrue/laravel-pinyin in a Laravel application?
- Install it with Composer using composer require overtrue/laravel-pinyin. The service provider and Pinyin facade are registered automatically through Laravel package auto-discovery, so no manual registration is required on supported versions. If you disable discovery, add the provider and facade alias to your config/app.php manually. No migrations, queues, or external services are involved, which makes the install fully reversible.
- Which Laravel and PHP versions does laravel-pinyin support?
- The 6.1.0 release adds an illuminate/* ^13.0 constraint on top of the existing supported matrix, so it covers current Laravel releases including 13.x. You need PHP with the mbstring extension enabled, since the underlying overtrue/pinyin engine relies on multibyte string handling. Applications still on 5.x should treat 6.x as a major upgrade and review the facade and service provider changes first.
- How do I convert Chinese characters to pinyin with the Pinyin facade?
- Resolve the facade and call the convert method, for example Pinyin::convert('中国'), which returns the romanized string. The package also exposes helpers such as slug and sentence for common one-line transformations. Because the service is stateless, you can call it from controllers, Blade views, jobs, or Artisan commands without any bootstrapping concerns. You can also inject the underlying converter if you prefer constructor injection over the facade.
- Can I generate URL slugs from Chinese titles using this package?
- Yes, slug generation is one of the most common uses, and the package provides a slug-style call that converts Chinese text into a URL-safe pinyin string with a separator of your choice. This lets you turn titles like article headlines into readable, ASCII-only slugs instead of percent-encoded URLs. Keep in mind that polyphonic characters may occasionally romanize differently than a human would expect, so spot-check output for high-visibility content.
- How do I output pinyin without tone marks, or with tone numbers instead?
- The underlying engine supports several output modes, including tone marks, tone numbers, and plain pinyin without any tone information, and you can select the mode per call or set a default in the configuration file. Acronym or first-letter modes are also available when you only need initials. For slugs and sort keys, plain pinyin is usually the right choice; for display or teaching material, tone marks read better.
- Does laravel-pinyin handle polyphonic characters and surname pronunciations correctly?
- Conversion is dictionary and heuristic driven, so characters with multiple readings such as 行, 重, and 长 can sometimes be romanized incorrectly depending on context. The engine includes surname-aware handling that improves results for Chinese personal names, but it is not a full linguistic parser. For slugs or sort keys the occasional mismatch is cosmetic, while search indexing or legal-name romanization should include a spot-check acceptance step against your real corpus.
- How do I customize the separator, defaults, and other options?
- Publish the package configuration with php artisan vendor:publish and select the pinyin config tag, which creates a config file in your application. From there you can set default output style, separator, and options such as memory limits for the dictionary tables. Per-call options on the facade override the published defaults, so you can keep a global baseline and still tailor individual conversions.
- Is laravel-pinyin safe to run in production under PHP-FPM or Laravel Octane?
- The service itself is stateless and does no I/O, so it is safe in any runtime, but the engine ships sizable dictionary tables that are loaded into PHP memory. Under PHP-FPM with many workers that baseline memory is paid per worker, so verify your memory_limit and headroom on the target container. Under Octane the dictionary is loaded once per worker and retained across requests, which is a net win compared with per-request bootstrap.
- How do I test pinyin conversion in my Laravel test suite?
- Because conversion is deterministic for a given input and option set, you can assert exact strings in feature or unit tests without mocking anything. Write a small dataset of realistic inputs from your own corpus, including names and polyphonic characters, and assert the expected pinyin or slug output. This also gives you a regression suite that will catch behaviour changes when you upgrade the package or the underlying engine.
- What are the alternatives if laravel-pinyin is not maintained or I need traditional Chinese?
- The package is a thin wrapper, so the cheapest fallback is to depend on the underlying overtrue/pinyin engine directly and drop the provider and facade. Because the API surface is small, convert, slug, and sentence, forking or vendoring the wrapper is also inexpensive. The engine already supports traditional-to-simplified handling and surname-aware modes, so verify those options before adding a second library to your stack.