Polyfill Iconv Laravel Package

Getting Started

Install the polyfill via Composer—no further configuration required:

composer require symfony/polyfill-iconv

It auto-registers via Composer’s autoloader and activates transparently when iconv_* functions are called and ext-iconv isn’t loaded. First use case: confirm polyfill is active in development or CI where ext-iconv is omitted:

// In a script or test
$hasIconvExt = extension_loaded('iconv');
$polyfillLoaded = class_exists('Symfony\Polyfill\Iconv\Iconv');

if (!$hasIconvExt && $polyfillLoaded) {
    $converted = iconv('UTF-8', 'ASCII//IGNORE', 'Zürich'); // → "Zrich"
    echo $converted; // Verify behavior
}

Implementation Patterns

• Zero-Change Migration: Use iconv() and related functions (iconv_strlen, iconv_substr, iconv_mime_encode) identically to native — no wrapper or adapter needed. Ideal for refactoring legacy code or running third-party libraries expecting iconv.
• Stack Pairing: Combine with symfony/polyfill-mbstring to cover all multibyte string operations in environments where neither ext-iconv nor ext-mbstring are guaranteed (e.g., shared hosting, lightweight containers).
• CI Guardrails: Add conditional require-dev only if strict environment control is needed, but production use is safest for portability (e.g., Laravel apps deployed to Heroku, Docker, or AWS Lambda with minimal PHP builds).
• Framework Autoloading: In Laravel, no service provider or config tweaks are needed—the polyfill loads automatically via Composer’s files autoloading (as defined in vendor/symfony/polyfill-iconv/composer.json).

Gotchas and Tips

• Performance Tradeoffs: Polyfill fallbacks are significantly slower (~2–5×) for heavy operations (e.g., processing 10k+ strings). Profile in staging—consider pre-converting input to UTF-8 or caching results for hot paths.
• Flag Limitations: //TRANSLIT uses basic ASCII fallbacks (e.g., é → e), but complex scripts (Arabic, Thai, CJK) may render incorrectly. //IGNORE is robust, but verify with your target locales.
• iconv_get_encoding() Unavailable: This function isn’t polyfilled—use iconv('UTF-8', 'UTF-8', $str) or mb_internal_encoding() to verify encoding context instead.
• Extension Priority: If ext-iconv is present, the polyfill won’t override it (PHP extensions take precedence). To force polyfill for testing: php -d extension=-iconv artisan test.
• Debugging Aid: Add a diagnostic route or middleware in Laravel to log polyfill usage:

// In app/Http/Middleware/PolyfillMonitor.php
if (!extension_loaded('iconv') && class_exists(\Symfony\Polyfill\Iconv\Iconv::class)) {
    \Log::info('Polyfill iconv in use');
}