Weave Code
Polyfill Iconv Laravel Package
symfony/polyfill-iconv
Native PHP polyfill for the iconv extension, providing drop-in implementations of iconv functions (except ob_iconv_handler). Useful when iconv isn’t available, helping ensure consistent behavior across environments.
Symfony polyfill for the Iconv extension
Frequently asked questions about Polyfill Iconv
- How do I install symfony/polyfill-iconv in a Laravel project?
- Run `composer require symfony/polyfill-iconv` to install the package. For development-only use (e.g., testing environments without the native extension), add `--dev`. The polyfill will automatically activate if the `iconv` extension is missing, requiring no additional configuration.
- Does symfony/polyfill-iconv work with Laravel’s built-in string/translation utilities?
- Yes, the polyfill integrates transparently with Laravel’s `Str::of()`, `File` facade, and `Illuminate/Translation` components. These utilities will automatically use the polyfill’s `iconv` functions if the native extension is unavailable, ensuring consistent encoding behavior across your application.
- Which Laravel versions officially support symfony/polyfill-iconv?
- The package is compatible with Laravel 8+ (PHP 7.4+) and Laravel 9/10 (PHP 8.0+). It relies on Symfony’s polyfill ecosystem, which aligns with Laravel’s long-term support (LTS) releases. Test thoroughly if using Laravel 11+ or PHP 8.3, as Symfony may introduce breaking changes.
- What iconv functions are *not* supported by this polyfill, and how do I handle them?
- The polyfill excludes `ob_iconv_handler` and `iconv_get_encoding()`. For `iconv_get_encoding()`, use `mb_internal_encoding()` as a fallback. For `ob_iconv_handler`, consider alternatives like `mbstring` functions or output buffering with `mb_convert_encoding()` in your Laravel middleware or service providers.
- Will using this polyfill impact performance in production?
- Yes, the polyfill introduces a 2–5× latency overhead for encoding operations compared to the native `iconv` extension. Monitor high-volume operations (e.g., batch processing or API endpoints) and consider enabling the native extension in production if possible. For critical paths, test with `php -d extension=iconv` to compare performance.
- How can I test if symfony/polyfill-iconv is working in my Laravel app?
- Run your tests with the `iconv` extension disabled: `php -d extension=iconv artisan test`. Alternatively, use a feature flag to toggle the polyfill in staging and validate encoding consistency for user-generated content, file uploads, or translations. Check logs for `iconv()` warnings if the polyfill fails silently.
- Can I use symfony/polyfill-iconv alongside symfony/polyfill-mbstring?
- Yes, these polyfills are designed to work together. Use `symfony/polyfill-mbstring` for multibyte string functions (e.g., `mb_convert_encoding`) and `symfony/polyfill-iconv` for legacy `iconv` compatibility. Laravel’s `Str` helpers and `File` facade will prioritize the native extensions when available, falling back to polyfills as needed.
- Are there alternatives to symfony/polyfill-iconv for Laravel?
- For basic encoding needs, Laravel’s `Str::of()` or `mbstring` functions (with the `mbstring` extension) may suffice. However, `symfony/polyfill-iconv` is the most robust solution for environments lacking the `iconv` extension, especially when working with legacy systems or shared hosting. Avoid rolling your own polyfill, as edge cases (e.g., complex scripts) are hard to handle correctly.
- How do I detect if the polyfill is being used in production?
- Add middleware to check `extension_loaded('iconv')` and log usage. Alternatively, wrap critical `iconv` calls in a helper function that logs invocations. For Laravel, you could extend the `AppServiceProvider` to inject a polyfill detector service. This helps identify environments where the polyfill is active and monitor for potential issues.
- What should I do if the polyfill fails to handle a specific encoding (e.g., Thai or Arabic)?
- The polyfill handles basic encodings (e.g., UTF-8, ISO-8859-1) reliably, but complex scripts or legacy encodings (e.g., EUC-JP) may produce suboptimal results. For such cases, enable the native `iconv` extension in production or use `mbstring` functions as a fallback. Test edge cases with `mb_detect_encoding()` or `mb_convert_encoding()` in your Laravel validation logic.
Weaver
How can I help you explore Laravel packages today?