Polyfill Iconv Laravel Package

Getting Started

Minimal Steps

1. Installation: Add the package via Composer:

   composer require symfony/polyfill-iconv
   

   No additional configuration is required—it auto-loads and replaces missing iconv functions.

2. First Use Case: Test basic encoding conversion in a Laravel controller or service:

   use Symfony\Polyfill\Iconv\Iconv;
   
   // Example: Convert UTF-8 to ASCII, ignoring unsupported characters
   $text = "Café";
   $converted = iconv('UTF-8', 'ASCII//IGNORE', $text); // Outputs: "Cafe"
   

3. Verify Functionality: Disable ext-iconv locally to test polyfill behavior:

   php -d extension=iconv.ini artisan tinker
   

   Then run:

   iconv('UTF-8', 'UTF-16', 'Hello'); // Should work without native extension
   

4. Key Functions Supported:

   • iconv(), iconv_strlen(), iconv_strpos(), iconv_substr()
   • iconv_mime_encode(), iconv_mime_decode()
   • Transliteration flags (e.g., //TRANSLIT, //IGNORE).

Implementation Patterns

Usage Patterns

1. Automatic Fallback: The polyfill replaces missing iconv functions without manual checks. Use native syntax:

   // Works in all environments (with or without ext-iconv)
   $cleaned = iconv('UTF-8', 'ASCII//TRANSLIT', $userInput);
   

2. Laravel-Specific Integrations:

   • Form Requests: Sanitize multilingual input:

     public function rules()
     {
         return [
             'name' => 'string|max:255|iconv:UTF-8/ASCII//IGNORE', // Custom validator
         ];
     }
     

   • File Handling: Ensure consistent encoding for uploaded files:

     $content = file_get_contents($path);
     $utf8Content = iconv('ISO-8859-1', 'UTF-8', $content);
     

3. Database Interactions: Normalize charset for queries or migrations:

   // In a migration or model observer
   $normalized = iconv('Windows-1252', 'UTF-8', $legacyData);
   

4. API Responses: Standardize encoding for internationalized responses:

   return response()->json([
       'message' => iconv('UTF-8', 'UTF-8//IGNORE', $userMessage),
   ]);
   

Workflows

1. CI/CD Pipeline: Force polyfill usage in test environments:

   # .github/workflows/tests.yml
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - run: php -d extension=iconv.ini -r "echo 'Native iconv available';"
         - run: php -d extension=-iconv.ini vendor/bin/phpunit
   

2. Legacy System Migration: Gradually replace mbstring with iconv:

   // Before: mbstring
   $length = mb_strlen($text, 'UTF-8');
   
   // After: iconv (polyfill-compatible)
   $length = iconv_strlen($text, 'UTF-8');
   

3. Multilingual Content Processing: Chain encoding operations for complex workflows:

   $processed = iconv('UTF-8', 'UTF-16', $text)
               -> iconv('UTF-16', 'ASCII//TRANSLIT', $text);
   

Integration Tips

• Laravel Helpers: Extend Str facade for encoding utilities:

  // app/Helpers/StrHelper.php
  if (!class_exists('Str')) {
      require __DIR__.'/../../vendor/laravel/framework/src/Illuminate/Support/Str.php';
  }
  
  class StrHelper extends Str {
      public static function iconv($string, $inCharset, $outCharset)
      {
          return iconv($inCharset, $outCharset, $string);
      }
  }
  

• Service Providers: Register polyfill-aware bindings:

  // app/Providers/AppServiceProvider.php
  public function boot()
  {
      if (!extension_loaded('iconv')) {
          $this->app->bind('encoding', function () {
              return new class {
                  public function convert($string, $from, $to) {
                      return iconv($from, $to, $string);
                  }
              });
          });
      }
  }
  

• Testing: Mock polyfill behavior in unit tests:

  // tests/Feature/EncodingTest.php
  public function test_iconv_polyfill()
  {
      if (extension_loaded('iconv')) {
          $this->markTestSkipped('Native iconv available; skip polyfill test.');
      }
  
      $result = iconv('UTF-8', 'ASCII//IGNORE', 'Café');
      $this->assertEquals('Cafe', $result);
  }
  

Gotchas and Tips

Pitfalls

1. Unsupported Functions:

   • ob_iconv_handler: Not supported. Use mbstring output buffering instead:

     ob_start('mb_output_handler');
     

   • iconv_get_encoding: Fall back to mb_internal_encoding():

     $encoding = mb_internal_encoding();
     

2. Transliteration Quirks:

   • Complex scripts (e.g., Arabic, Thai) may produce unexpected results. Test edge cases:

     $arabic = iconv('UTF-8', 'ASCII//TRANSLIT', 'محمد');
     // May output: "mohammad" (varies by PHP version)
     

3. Performance Bottlenecks:

   • Large-scale operations: Polyfill is 2–5× slower than native iconv. Profile with:

     composer require blackfire/php
     vendor/bin/blackfire run php artisan your:command
     

   • Batch processing: Offload to queues or use mbstring for high-throughput tasks.

4. Environment Mismatches:

   • Local vs. Production: Ensure consistent default_charset in php.ini or .env:

     DEFAULT_CHARSET=UTF-8
     

   • Docker: Explicitly disable ext-iconv in Dockerfile for testing:

     RUN docker-php-ext-disable iconv
     

5. False Positives:

   • function_exists('iconv'): Always returns true (even with polyfill). Use:

     if (extension_loaded('iconv')) {
         // Native extension available
     }
     

Debugging

1. Encoding Artifacts:

   • Mojibake: Check for ? or garbled characters. Debug with:

     var_dump(bin2hex($string)); // Hex dump to identify encoding issues
     

   • Common Fixes:

     // Force UTF-8 normalization
     $clean = iconv('UTF-8', 'UTF-8//IGNORE', $dirty);
     

2. Polyfill Detection:

   • Verify polyfill usage:

     if (strpos(iconv('UTF-8', 'UTF-8', 'test'), 'Symfony') !== false) {
         // Polyfill is active
     }
     

3. Log Encoding Warnings:

   • Add middleware to log iconv usage:

     // app/Http/Middleware/CheckEncoding.php
     public function handle($request, Closure $next)
     {
         if (!extension_loaded('iconv')) {
             Log::warning('Using iconv polyfill; consider enabling ext-iconv in production.');
         }
         return $next($request);
     }
     

Tips

1. Configuration:

   • Laravel .env: Set default charset:

     APP_CHARSET=UTF-8
     

   • PHP.ini: Ensure default_charset matches:

     default_charset = "UTF-8"
     

2. Extension Points:

   • Custom Polyfill: Extend functionality by wrapping iconv:

     function custom_iconv($inCharset, $outCharset, $string)
     {
         $result = iconv($inCharset, $outCharset, $string);
         // Add custom logic (e.g., logging, validation)
         return $result;
     }
     

3. Performance Optimization:

   • Cache Results: For repeated conversions:

     $cache = new ArrayCache();
     $cached = $cache->remember("iconv_{$in}_{$out}_{$string}", 3600, function()