Symfony Polyfill Iconv

Symfony Polyfill Iconv provides a native PHP implementation of the functions exposed by PHP’s iconv extension, letting libraries depend on iconv-based character-set conversion without requiring the compiled extension to be installed on the host. When the real extension is present, it is used transparently; otherwise the polyfill supplies a compatible fallback.

It is part of the broader Symfony Polyfill family, which backfills missing or optional PHP features so that portable code can run consistently across heterogeneous PHP environments, from tightly locked-down shared hosting to minimal container images.

What You Get

• A drop-in polyfill for the core iconv functions, activated automatically when ext-iconv is missing
• Transparent pass-through to the native extension when it is installed, so you pay no penalty on well-equipped hosts
• PSR-4 autoloading with a bootstrap file wired through Composer for zero-config installation
• A permissive MIT license and a stable, widely-depended-on maintenance track record

Common Use Cases

• Ensuring a library works on hosts where the iconv extension is not compiled in
• Standardizing character-set conversion behavior across CI, staging and production environments
• Shipping portable packages that must run on minimal or locked-down PHP installations

Under The Hood

Architecture - The package centers on a single Iconv.php class in the Symfony\Polyfill\Iconv namespace that reimplements iconv, iconv_strlen, iconv_substr, iconv_strpos and related functions in pure PHP, backed by an encoding table under Resources. A bootstrap.php (with a PHP 8-specific bootstrap80.php variant) defines the global iconv_* functions only when the native extension is not loaded, so it is inert on hosts that already have ext-iconv.

Tech Stack - Pure PHP targeting 7.2+, distributed via Composer with PSR-4 autoloading and a files autoload entry for the bootstrap. It declares provide: ext-iconv so dependency resolvers treat it as satisfying the extension requirement. No runtime dependencies beyond PHP itself.

Code Quality - The implementation is compact, well-scoped, and maintained by the Symfony core team as part of the polyfill monorepo, which carries a shared CI and test suite. Function signatures mirror the native extension closely to preserve behavioral compatibility.

API Design - There is effectively no learning curve: consumers simply require the package and call the standard iconv functions as they always would. The polyfill is invisible in day-to-day use, which is exactly the intended developer experience.