Polyfill Intl Grapheme Laravel Package

Getting Started

This polyfill provides grapheme_* functions (e.g., grapheme_strlen, grapheme_substr, grapheme_strpos) for environments where the intl extension is not installed or is incomplete. Start by installing it via Composer:

composer require symfony/polyfill-intl-grapheme

Once installed, it automatically patches the grapheme_* functions at runtime — no configuration required. Your first use case is likely safely handling multi-byte Unicode grapheme clusters (e.g., emoji, accented characters) in strings, especially when migrating from or supporting servers without intl.

Implementation Patterns

• Drop-in Replacement: Replace vulnerable string functions (strlen, substr, strpos, etc.) with their grapheme_* equivalents only where needed (e.g., user input processing, UI display logic, database sanitization).
  Example:

  // Count visible characters in "A̐éö" (3 graphemes, 5 codepoints)
  $len = grapheme_strlen("A̐éö"); // → 3
  

• Legacy Compatibility Layer: Use a helper function that wraps polyfill or native functions:

  if (!function_exists('grapheme_strlen')) {
      require_once __DIR__ . '/vendor/symfony/polyfill-intl-grapheme/bootstrap.php';
  }
  

• Framework Integration (e.g., Laravel): In Laravel projects, register the polyfill early via AppServiceProvider or use Laravel’s built-in polyfill support. Many Laravel string helpers (e.g., Str::length()) automatically benefit from it when intl is unavailable.

Gotchas and Tips

• No Intl fallback: Unlike other Symfony polyfills, this one only provides the grapheme_* functions — it does not add intl coverage elsewhere. Ensure you’re not conflating it with symfony/polyfill-intl-normalizer or symfony/polyfill-intl-icu.
• Performance: Polyfilled functions are slower than native C implementations. Cache results for large strings (e.g., in queued jobs, DTOs, or caching layers).
• Debugging: Enable xdebug.show_exception_trace = 0 if you see cryptic errors — polyfills sometimes interact poorly with Xdebug’s stack tracing.
• Extension Conflicts: If intl is installed but outdated (e.g., missing grapheme_* in older PHP versions), the polyfill will still activate. Check function_exists('grapheme_strlen') at runtime if needed.
• Testing Tip: Write unit tests for emoji-heavy strings ("flag 🏳️‍🌈", "é + combining acute") to catch grapheme-related regressions.