Weave Code
Polyfill Iconv Laravel Package
symfony/polyfill-iconv
Native PHP polyfill for the iconv extension, providing implementations of common iconv functions (except ob_iconv_handler). Useful when iconv isn’t available, ensuring consistent character set conversion 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` in your Laravel project directory. The package auto-loads via Composer’s autoloader, so no additional configuration is needed. Laravel’s service container and helpers (e.g., `Str::of()`) will automatically use the polyfill if `ext-iconv` is missing.
- Does symfony/polyfill-iconv work with Laravel’s File facade or Storage disks?
- Yes, the polyfill integrates seamlessly with Laravel’s File facade and Storage disks. If `ext-iconv` is unavailable, operations like file reading/writing or disk uploads will use the polyfill’s encoding functions transparently. Test with `php -d extension=-iconv` to verify behavior in your CI/CD pipeline.
- Which Laravel versions officially support symfony/polyfill-iconv?
- The package is compatible with Laravel 5.5+ and PHP 7.2+. It follows Symfony’s backward compatibility guarantees, so it works with Laravel 6, 7, 8, 9, and 10 without issues. For Laravel 11+, check Symfony’s release notes for PHP 8.3+ compatibility, as iconv behavior may evolve.
- What iconv functions are *not* supported by this polyfill?
- The polyfill excludes `ob_iconv_handler` and `iconv_get_encoding()`. For these, use alternatives like `mbstring` functions (e.g., `mb_convert_encoding()`) or regex-based workarounds. Document unsupported features in your project’s encoding strategy to avoid runtime surprises.
- How can I test if symfony/polyfill-iconv is working in my Laravel app?
- Run `php -d extension=-iconv artisan test` to simulate an environment without `ext-iconv`. Write unit tests checking `function_exists('iconv')` and test edge cases like Arabic or CJK text. Use Laravel’s `phpunit` with a `TestCase` that disables `ext-iconv` via `putenv('PHP_EXT_ICONV=0')`.
- Will using this polyfill slow down my Laravel application?
- Yes, the polyfill introduces a 2–5× performance overhead compared to native `ext-iconv`. Profile with Blackfire or Laravel Telescope to identify bottlenecks. Mitigate by enabling `ext-iconv` in production or caching frequent conversions (e.g., with Laravel’s cache system).
- Can I use symfony/polyfill-iconv for multilingual Laravel apps (e.g., Arabic, Chinese)?
- Yes, but test thoroughly with real-world datasets (e.g., Unicode CLDR). The polyfill handles basic encoding conversions, but complex scripts (e.g., Thai, Arabic) may require additional validation. Log encoding artifacts in production to catch edge cases early.
- Are there alternatives to symfony/polyfill-iconv for Laravel?
- For broader encoding support, consider `ext-mbstring` (if available) or libraries like `symfony/string` for text manipulation. However, `symfony/polyfill-iconv` is the most lightweight solution for `iconv`-specific needs, especially in environments where `ext-iconv` is unavailable.
- How do I handle production deployments where ext-iconv is inconsistent?
- Use Laravel’s environment detection (e.g., `if (!function_exists('iconv')) { ... }`) to gracefully fall back to the polyfill. Monitor encoding operations in production with middleware or error logging to catch inconsistencies. Document your fallback strategy in deployment notes.
- Does symfony/polyfill-iconv work with Laravel’s Str::of() helper?
- Yes, Laravel’s `Str::of()` and other string helpers will automatically use the polyfill if `ext-iconv` is missing. Test with `Str::of($text)->encode('UTF-8', 'ASCII//TRANSLIT')` in a `php -d extension=-iconv` environment to verify behavior.
Weaver
How can I help you explore Laravel packages today?