Polyfill Intl Icu Laravel Package

Getting Started

Install via Composer (automatically pulled in as a dependency when using Laravel or Symfony components); no manual configuration needed. Start using it immediately by writing code that relies on NumberFormatter, Collator, or Locale — the polyfill auto-registers via Composer’s autoload. Verify activation by calling class_exists('NumberFormatter') or function_exists('intl_is_failure'). Your first real-world use case: formatting currencies or numbers consistently across environments where ext-intl is absent — e.g., local development on minimal Docker images or shared hosting.

Implementation Patterns

• Write Portable i18n Code: Use ICU classes natively (new IntlDateFormatter(...), new Collator(...)) without conditional checks. The polyfill seamlessly patches missing functionality.
• Error Handling Consistency: Leverage ICU error APIs (intl_get_error_code(), intl_get_error_message()) to catch subtle formatting failures — especially useful when validating user-provided locale strings (e.g., new NumberFormatter($userLocale, ...)).
• Test Coverage in Restricted Environments: Run unit/integration tests in CI pipelines that omit ext-intl (e.g., GitHub Actions with minimal PHP builds), ensuring your i18n logic remains robust regardless of server configuration.

Gotchas and Tips

• English-Only Reality: The polyfill only supports the en locale — even if you request fr_FR, outputs will default to English formatting (e.g., dates as MM/dd/yyyy, numbers as 1,234.56). Add runtime guards (e.g., if (Locale::getDefault() !== 'en') { /* warn or fallback */ }) in early development.
• Silent Degradation: No exceptions are thrown for unsupported locales or features — incorrect formatting may occur without warning. Log Locale::getDefault() in debug mode during testing to catch misconfigurations.
• Performance Tradeoffs: ICU object instantiation (especially Collator and IntlDateFormatter) is 3–5× slower than native ext-intl. For high-volume operations (e.g., bulk currency formatting), precompute or cache results.
• Never Use for Non-English Production: Avoid deploying to multilingual apps without ext-intl — formatting, collation, and calendar rules for other locales will be incorrect. This polyfill is strictly a fallback, not a production i18n solution.
• Autoloader Precedence Works in Your Favor: If ext-intl is installed, it always overrides the polyfill — so you can safely include it project-wide without conditional logic.