Polyfill Laravel Package

Getting Started

Minimal Setup

1. Check your target platform Confirm the minimum PHP version your app must support:

   php -r "echo PHP_VERSION;"
   

   Also check required extensions such as mbstring or intl.

2. Install only the polyfills you need

   composer require symfony/polyfill-php80 symfony/polyfill-mbstring
   

   Use standalone packages, not the umbrella symfony/polyfill package. For example:

   • symfony/polyfill-php80 for str_contains(), str_starts_with(), etc.
   • symfony/polyfill-mbstring for mb_*() functions when mbstring is unavailable.
   • symfony/polyfill-intl-idn for idn_to_ascii().

3. First use case Install the PHP 8.0 polyfill and use the native function normally:

   $contains = str_contains('hello', 'ell'); // true
   

   In Laravel, Composer’s autoload bootstrap loads the polyfill files automatically. You normally do not import or call polyfill classes directly.

Implementation Patterns

1. Write Against Native PHP APIs

• Pattern: Use the polyfill to backfill missing functions, then write code as if the feature exists natively.
• Example:

  $firstKey = array_key_first(['a' => 1, 'b' => 2]); // 'a'
  

• This keeps code portable and avoids coupling application code to Symfony polyfill internals.

2. Extension Polyfills

• Pattern: Use extension polyfills only when the production/CI environment may lack that extension.
• Example:

  $length = mb_strlen('こんにちは'); // 5
  

• Install symfony/polyfill-mbstring if mbstring is optional in some deployments.

3. Keep the Polyfill Set Lean

• Prefer standalone packages over symfony/polyfill.
• Inspect why a polyfill is present:

  composer why symfony/polyfill-php80
  composer show symfony/polyfill-*
  

• Do not blindly add replace entries to composer.json; that can break transitive dependencies. Let Composer resolve polyfills unless you have a deliberate platform strategy.

4. Integration with Laravel

• Polyfills are loaded through Composer’s autoload.files, before Laravel boots. You usually do not need to register them in AppServiceProvider.
• Use polyfilled functions directly in helpers, actions, Blade templates, jobs, and Artisan commands.
• If a function is missing in a long-running process, first verify vendor/autoload.php is loaded and Composer’s autoload files are up to date:

  composer dump-autoload
  

5. Testing Compatibility

• Test on the minimum supported PHP version and on a modern PHP version.
• In CI, include at least one job without optional extensions such as mbstring if you rely on extension polyfills.
• Avoid mocking polyfill classes; test the native function/API your application uses.

Gotchas and Tips

Pitfalls

1. Requiring the Umbrella Package

   • Avoid symfony/polyfill unless you truly need every polyfill. It increases dependency surface and install size.
   • Prefer the specific symfony/polyfill-* package.

2. Calling Polyfill Internals Directly

   • Do not couple application code to classes like Symfony\Polyfill\.... Those are implementation details.
   • Call str_contains(), mb_strlen(), etc. normally.

3. DeepClone Changes in v1.43.2

   • v1.43.2 improves DeepClone error reporting for malformed payloads and speeds up deepclone_from_array().
   • Still test closures, resources, circular references, and complex object graphs:

     try {
         $copy = deepclone($payload);
     } catch (\Throwable $e) {
         report($e); // inspect malformed payload shape
     }
     

4. UTF-8 Handling

   • A polyfilled mbstring may not match every native extension edge case.
   • Validate external input with mb_check_encoding() where relevant, and test invalid UTF-8 cases explicitly.

5. Performance Expectations

   • Polyfills are conditional but not free. They add autoload/bootstrap checks and may add runtime overhead when actually used.
   • Keep unused polyfills out of the dependency graph where possible, but do not remove transitive polyfills without checking composer why.

6. Composer Platform Configuration

   • Use config.platform.php to resolve dependencies for the lowest PHP version you deploy:

     "config": {
         "platform": {
             "php": "8.1.0"
         }
     }
     

   • Setting this too high can omit polyfills needed by lower production runtimes.

Debugging Tips

1. Verify the Function Is Available

   if (!function_exists('str_contains')) {
       throw new \RuntimeException('str_contains polyfill is not loaded.');
   }
   

2. Check Extension Availability

   if (!extension_loaded('mbstring')) {
       // Confirm symfony/polyfill-mbstring is installed and autoloaded.
   }
   

3. Inspect Composer Autoload Files

   • If a polyfill seems installed but not active:

     composer dump-autoload
     

   • Check vendor/composer/autoload_files.php to confirm the polyfill bootstrap is registered.

4. Debug DeepClone Failures

   • In v1.43.2, malformed payload reporting is closer to the native extension’s behavior.
   • Catch and log the exception, then reduce the payload to the smallest failing object/array to isolate unsupported data.

5. Laravel Cache Is Not the Cause

   • php artisan config:clear, route caching, and view caching do not control Composer polyfills.
   • Polyfill loading is a Composer/autoload concern.

Extension Points

1. Composer Platform Strategy

   • Use config.platform.php in composer.json to align dependency resolution with your minimum production PHP version.

2. Application-Level Wrappers

   • If your app needs consistent behavior across environments, wrap native/polyfilled functions in your own helper or service.
   • Do not subclass or depend on Symfony polyfill internals for business logic.

3. CI Matrix

   • Add CI jobs for:
     • Minimum supported PHP version.
     • Modern PHP version.
     • Missing optional extensions when using extension polyfills.
   • This catches both missing-polyfill and native-extension behavior differences.