- How do I install overtrue/pinyin in a Laravel project?
- Run `composer require overtrue/pinyin` in your project root. The package integrates seamlessly with Laravel’s service container and supports PSR-4 autoloading. No additional Laravel-specific setup is required beyond requiring the package.
- Does overtrue/pinyin support Laravel’s Str::helper for Pinyin conversion?
- No, but you can easily bind the package to Laravel’s service container and create a facade (e.g., `Pinyin::sentence()`) or use a helper like `Str::pinyin()` by extending Laravel’s `Str` class with the package’s logic.
- What Laravel versions does overtrue/pinyin support?
- The package works with Laravel 8+ and PHP 8.0+. It has no framework-specific dependencies, so it integrates cleanly with modern Laravel applications. Older Laravel versions may require minor adjustments for service binding.
- How accurate is the Pinyin conversion for multi-syllable words like ‘中国’?
- The package uses the `mozillazg/pinyin-data` dictionary, which handles multi-syllable words accurately (e.g., ‘中国’ → ‘zhōngguó’). For niche terms or slang, supplement the default dictionary with a custom one via the `addDictionary()` method.
- Can I customize the output format (e.g., tone marks, numbers, or no tones)?
- Yes. Use `ToneStyle::SYMBOL` (e.g., ‘nǐ hǎo’), `ToneStyle::NUMBER` (e.g., ‘ni3 hao3’), or `ToneStyle::NONE` (e.g., ‘ni hao’) as the second argument in methods like `Pinyin::sentence()`. The package also supports string-based formats like ‘symbol’, ‘number’, or ‘none’.
- How do I handle traditional Chinese characters (e.g., ‘國’ → ‘guó’)?
- The package defaults to simplified Chinese. For traditional characters, replace the default dictionary with one tailored to traditional Chinese (e.g., `mozillazg/pinyin-data-traditional`) or extend the package to support both via conditional logic.
- Is overtrue/pinyin suitable for high-traffic Laravel apps where performance matters?
- Yes, but optimize for repeated conversions. Cache results for static data (e.g., product names) and pre-split common terms. The package’s runtime overhead is minimal (~1–5ms per conversion), but batch processing may benefit from queue workers.
- How do I add custom words to the dictionary for domain-specific terms?
- Use the `addDictionary()` method to inject a custom dictionary array or file. For example: `$pinyin->addDictionary(['我的品牌' => 'wodepinpai']);`. This overrides default entries for your terms, making it ideal for brand names or jargon.
- Does overtrue/pinyin work with mixed Chinese-English text (e.g., ‘中文-English’)?
- Yes, but test edge cases. The package processes Chinese characters while leaving non-Chinese text unchanged. For mixed input, use `Pinyin::sentence()` with a custom separator (e.g., hyphen) to ensure clean output like ‘zhongwen-english’.
- What are the alternatives to overtrue/pinyin, and why choose this package?
- Alternatives include `xpinyin` or `php-pinyin`, but overtrue/pinyin stands out for its accuracy with multi-syllable words, tone customization, and Laravel-friendly design. It also supports traditional Chinese and offers better performance for large-scale conversions due to its optimized dictionary structure.