Getting Started

Minimal Steps

Installation: Add the package via Composer in your Laravel project:
```
composer require symfony/polyfill-intl-normalizer
```
No additional configuration is required—it auto-loads when the intl extension is missing.

First Use Case: Normalize Unicode strings in a Laravel application where the intl extension is unavailable. For example, in a controller or service:

use Symfony\Component\Polyfill\Intl\Normalizer;

$text = "Café";
$normalized = Normalizer::normalize($text, Normalizer::FORM_C);
// Outputs: "Cafe\u00E9" (composed form)

Where to Look First:
- Documentation: Symfony Polyfill README
- Source Code: Focus on Normalizer.php in the package for implementation details.
- Laravel Integration: Check Laravel’s Str helper for built-in Unicode handling (e.g., Str::ascii()), which may already use this polyfill internally.

Implementation Patterns

Usage Patterns

Basic Normalization: Use the package for standard Unicode normalization forms (NFC, NFD, etc.) in Laravel applications:

// Normalize to composed form (NFC)
$normalized = Normalizer::normalize($string, Normalizer::FORM_C);

// Normalize to decomposed form (NFD)
$decomposed = Normalizer::normalize($string, Normalizer::FORM_D);

Integration with Laravel Helpers: Leverage Laravel’s Str helper, which may internally use this polyfill for Unicode handling:

use Illuminate\Support\Str;

$slug = Str::slug("Café", '-', Normalizer::FORM_C);
// Outputs: "cafe" (normalized before slug generation)

Custom Text Processing: Use normalizer_get_raw_decomposition() for advanced use cases like:
- Legacy Data Migration: Reverse-engineer decomposed Unicode strings.
- Debugging: Inspect how Unicode characters are decomposed for auditing or compliance.
```
$decomposed = Normalizer::normalize("Café", Normalizer::FORM_D);
$rawDecomposition = Normalizer::getRawDecomposition($decomposed);
```

Service Layer Integration: Create a dedicated service for Unicode normalization to centralize logic:

namespace App\Services;

use Symfony\Component\Polyfill\Intl\Normalizer;

class UnicodeNormalizer
{
    public function normalizeToNFC(string $text): string
    {
        return Normalizer::normalize($text, Normalizer::FORM_C);
    }

    public function getDecomposition(string $text): array
    {
        return Normalizer::getRawDecomposition($text);
    }
}

$this->app->singleton(UnicodeNormalizer::class, function ($app) {
    return new UnicodeNormalizer();
});

Validation Rules: Use the polyfill to enforce Unicode normalization in Laravel validation rules:

use Illuminate\Validation\Rule;

$validator = Validator::make($request->all(), [
    'username' => [
        'string',
        Rule::custom(function ($attribute, $value) {
            return Normalizer::normalize($value, Normalizer::FORM_C) === $value;
        })->message('Username must use composed Unicode characters.'),
    ],
]);

Workflows

Legacy System Integration:
- Normalize text from legacy databases or APIs that use inconsistent Unicode encoding.
- Example: Clean up data before importing into Laravel:
```
$legacyData = "Caf\u00E9"; // Inconsistent encoding
$cleanData = Normalizer::normalize($legacyData, Normalizer::FORM_C);
```
Multilingual Applications:
- Ensure consistent Unicode handling across languages in a global application.
- Example: Normalize user-generated content before storage:
```
$userInput = "Naïve";
$normalizedInput = Normalizer::normalize($userInput, Normalizer::FORM_C);
User::create(['name' => $normalizedInput]);
```

Search and Indexing:

Normalize text before indexing in Laravel Scout or Algolia to improve search relevance:

$searchableText = Normalizer::normalize($post->title, Normalizer::FORM_C);
$post->searchableData = ['title' => $searchableText];

Debugging and Auditing:

Use normalizer_get_raw_decomposition() to inspect Unicode strings for debugging or compliance:

$text = "Café";
$decomposed = Normalizer::normalize($text, Normalizer::FORM_D);
$rawDecomposition = Normalizer::getRawDecomposition($decomposed);
Log::debug("Unicode decomposition:", ['text' => $text, 'decomposition' => $rawDecomposition]);

Integration Tips

Leverage Laravel’s Str Helper: The Str helper may already use this polyfill internally. Check its source code for existing Unicode handling.

Cache Normalized Results: For performance-critical applications, cache normalized strings to avoid repeated processing:

$normalized = Cache::remember("normalized_{$string}", now()->addHours(1), function () use ($string) {
    return Normalizer::normalize($string, Normalizer::FORM_C);
});

Fallback to Native intl: If performance is critical and the intl extension is available, bypass the polyfill:

if (extension_loaded('intl')) {
    $normalized = Normalizer::normalize($string, Normalizer::FORM_C);
} else {
    // Use polyfill logic
}

Testing: Write tests to ensure Unicode normalization behaves as expected across environments:

use Symfony\Component\Polyfill\Intl\Normalizer;

public function testUnicodeNormalization()
{
    $this->assertEquals("Cafe\u00E9", Normalizer::normalize("Café", Normalizer::FORM_C));
    $this->assertEquals("Cafe\u0301", Normalizer::normalize("Café", Normalizer::FORM_D));
}

CI/CD Pipeline: Ensure your CI pipeline tests the polyfill by simulating environments without the intl extension. Use Docker or PHP’s disable_functions to test fallback behavior.

Gotchas and Tips

Pitfalls

Performance Overhead:
- The polyfill is slower than the native intl extension (5–20x for decomposition operations). Avoid using normalizer_get_raw_decomposition() in high-frequency loops without caching.
- Mitigation: Cache results or enforce the intl extension in production.
mbstring Dependency: The polyfill requires the mbstring extension. If it’s disabled, the package will fail silently or throw errors.
- Mitigation: Add a runtime check:
```
if (!extension_loaded('mbstring')) {
    throw new RuntimeException('The mbstring extension is required for Unicode polyfills.');
}
```

Edge Cases in Unicode Handling:

Complex Unicode sequences (e.g., emoji, surrogate pairs, combining characters) may not decompose as expected.

Mitigation: Test thoroughly with edge cases:

$edgeCases = [
    '🇺🇸',       // Emoji sequence
    'Ź',          // Combining character
    '😊',         // Single emoji
    'A\u030A',    // Decomposed character
];
foreach ($edgeCases as $text) {
    $decomposed = Normalizer::getRawDecomposition($text);
    // Validate expected behavior
}

Inconsistent Behavior Across PHP Versions: The polyfill may behave differently across PHP versions, especially for newer Unicode standards.
- Mitigation: Pin the package version in composer.json to avoid unexpected changes:
```
"symfony/polyfill-intl-normalizer": "^1.38.0"
```
Laravel-Specific Quirks:
- If Laravel’s Str helper or other components rely on the intl extension internally, the polyfill might not fully replicate their behavior.
- Mitigation: Test integration points (e.g., Str::slug(), Str::ascii()) to ensure consistency.

Debugging

Verify Polyfill Activation: Check if the polyfill is being used instead of the native intl extension:

if (!extension_loaded('intl')) {
    $reflection = new ReflectionClass(\Symfony\Component\Polyfill\Intl\Normalizer::class);
    Log::info('Using polyfill for Normal

Polyfill Intl Normalizer Laravel Package