Polyfill Intl Normalizer Laravel Package

Getting Started

This package is a drop-in fallback for PHP applications that rely on the Normalizer class from the intl extension, but need to run on environments where that extension is not installed (e.g., shared hosting or minimal Docker containers).

First use case: Detect if Normalizer exists and fall back gracefully — but with this polyfill, you don’t need to — just use Normalizer::normalize() as usual. Composer will auto-install it when required (via symfony/polyfill-intl-* or direct dependency).

Start here:

• Read the Normalizer docs on PHP.net — the polyfill mirrors the exact API.
• Run composer require symfony/polyfill-intl-normalizer to install.
• Then write code using Normalizer::normalize($string, Normalizer::FORM_C) — it just works on non-intl-enabled systems.

Implementation Patterns

• Universal string normalization: Use in validation layers (e.g., sanitizing usernames, emails, or slugs) where case/fold equivalence matters across locales:

  $safeInput = Normalizer::normalize(trim($_POST['username']), Normalizer::FORM_C);
  

• Transliteration safety net: Before comparing user input to database values (especially in multi-language apps), normalize both sides to NFC (Canonical Decomposition, then Canonical Composition):

  $dbTerm = Normalizer::normalize($row['title'], Normalizer::FORM_C);
  $query  = Normalizer::normalize($searchTerm, Normalizer::FORM_C);
  if ($dbTerm === $query) { /* match */ }
  

• Debugging normalization: When behavior differs across servers, use Normalizer::isNormalized($string, Normalizer::FORM_C) to gate heavy normalization logic.
• Integration with ORM: Wrap column values in business logic before query building (e.g., Elasticsearch/SQL searches) to ensure consistent matches regardless of Unicode decomposition.

Gotchas and Tips

• No performance magic: The polyfill uses pure PHP + mbstring — it’s slower than the C-based intl extension, especially for long strings. Profile before using in hot loops.
• Missing constants: Only Normalizer::FORM_* constants are defined (C, D, KC, KD). Using undefined constants (e.g., Normalizer::YES) will fail — always rely on Normalizer::FORM_* values.
• mbstring.required: Requires the mbstring extension; if missing, polyfill fails silently with E_USER_WARNING. Verify extension_loaded('mbstring') in dev environments.
• Case folding ≠ normalization: For case-insensitive comparison, don’t use normalize() alone — combine with mb_strtolower() or Normalizer::normalize($s, Normalizer::FORM_KC)->strtolower().
• Testing tip: Simulate lack of intl by overriding class_exists('Normalizer') in unit tests via reflection, or set up a GitHub Actions job with ext-intl: false.
• Upgrade safety: The polyfill keeps BC. Check CHANGELOG.md when upgrading — rarely needed, but critical if relying on edge-case behaviors (e.g., malformed UTF-8).