symfony/polyfill-mbstring

polyfill-mbstring is part of the Symfony Polyfill project — a family of components that reimplement PHP extension functions in plain PHP so libraries can depend on that functionality without requiring the corresponding native extension. This package specifically reimplements the Mbstring (multibyte string) extension’s functions in pure PHP, backed by ext-iconv for the underlying character-encoding conversions, so code calling mb_strlen(), mb_substr(), and similar functions keeps working even on PHP installations where ext-mbstring isn’t compiled in.

It registers itself via Composer’s provide mechanism ("provide": {"ext-mbstring": "*"}), meaning other packages can simply require ext-mbstring and get either the real extension or this shim transparently, whichever is available. It automatically prefers the native extension for performance when present, only falling back to the polyfill’s pure-PHP implementations when necessary — making it one of the most widely-pulled-in transitive dependencies in the PHP ecosystem, since so many packages (including much of Symfony itself) declare a soft dependency on mbstring this way.

What You Get

• Pure-PHP implementations of core Mbstring functions (mb_strlen, mb_substr, mb_strtoupper, and others)
• Composer provide: ext-mbstring declaration so dependents can require the extension abstractly
• Automatic preference for the native extension when present, falling back to the polyfill only when needed
• PHP 7.2+ compatible bootstrap files that conditionally define functions only if missing
• Zero-configuration drop-in behavior — no code changes required by consuming applications

Common Use Cases

• Running PHP applications on minimal or locked-down hosting environments without ext-mbstring compiled in
• Library authors declaring an abstract ext-mbstring dependency without forcing consumers to install the real extension
• CI/CD or Docker images that intentionally omit optional PHP extensions to keep image size small
• Ensuring consistent multibyte-string behavior across PHP installations with varying extension availability

Under The Hood

Architecture: The package consists of a Mbstring.php class implementing the multibyte-string functions as static methods, plus versioned bootstrap.php/bootstrap72.php/bootstrap80.php files that conditionally define the global mb_* function names (only if they don’t already exist as native functions), delegating to the Mbstring class implementation. This bootstrap-based conditional-definition pattern is the standard architecture shared across all symfony/polyfill-* packages, allowing the shim to be a complete no-op when the real extension is already loaded.

Tech Stack: Pure PHP (100% of tracked bytes), requiring PHP >=7.2 and the ext-iconv extension (which is far more commonly available than mbstring) to perform the actual character-encoding conversions underlying the multibyte operations. As a Composer package it declares provide: {"ext-mbstring": "*"}, the mechanism Composer uses to satisfy other packages’ require: {"ext-mbstring": "*"} constraints without the real extension being present.

Code Quality: This repository is a read-only, automatically-published split of the main symfony/polyfill monorepo (noted in its README, which points to the main Polyfill README for further detail) — the canonical test suite and CI configuration live in that parent monorepo rather than in this split repo itself, so this standalone checkout contains only the shippable source (Mbstring.php, bootstrap files, Resources) without its own test directory. With 39 contributors and steady incremental releases (v1.34 through v1.38.2 across recent months), maintenance is active and consistent with Symfony’s broader component release cadence.

API Design: There is effectively zero API surface for consumers — this package is designed to be required transitively and never interacted with directly; once installed, code simply calls the standard mb_* global functions exactly as it would with the native extension, with no wrapper classes, configuration, or explicit initialization required.