Getting Started

Minimal Steps

Installation:
```
composer require symfony/polyfill-php86
```
Laravel’s autoloader will handle the rest—no manual includes or configuration are needed.

First Use Case: Use clamp() to constrain values in validation logic:

use Symfony\Polyfill\Php86\clamp;

// Example: Sanitize user input for a form field (e.g., age)
$sanitizedAge = clamp((int) $request->input('age'), 0, 120);

Where to Look First:
- Polyfill Functions: Check vendor/symfony/polyfill-php86/ for source code (e.g., clamp.php).
- Laravel Integration: Test in a controller or service layer first (e.g., app/Http/Controllers/).
- Documentation: Symfony’s main polyfill README for broader context.

Implementation Patterns

Usage Patterns

Conditional Polyfill Usage: Check for native function availability before using the polyfill to avoid redundancy in PHP 8.6+:

if (function_exists('clamp')) {
    $value = clamp($input, $min, $max);
} else {
    // Fallback logic (e.g., manual clamping)
}

Laravel-Specific Integrations:

Validation Rules: Replace custom clamping logic in App\Rules:

public function passes($attribute, $value) {
    return clamp($value, 1, 100) === $value; // Ensure value is within bounds
}

Form Requests: Use clamp() in withValidator or passes methods:

public function passes($attribute, $value) {
    return clamp($value, 0, 1000) === $value; // Validate numeric ranges
}

Collections: Leverage ARRAY_FILTER_USE_VALUE in custom collection methods:

public function filterByValue($callback) {
    return $this->items->filter(fn($value) => $callback($value), ARRAY_FILTER_USE_VALUE);
}

Enum Support: Use SortDirection for type-safe sorting in APIs or query builders:

use Symfony\Polyfill\Php86\SortDirection;

// Example: API request sorting
$direction = $request->input('sort_direction') === 'desc'
    ? SortDirection::DESCENDING
    : SortDirection::ASCENDING;

Testing: Mock polyfill functions in PHPUnit to test both polyfilled and native behavior:

// tests/Feature/ClampTest.php
public function testClampFunction() {
    if (function_exists('clamp')) {
        $this->assertEquals(10, clamp(5, 10, 20));
    } else {
        // Test fallback logic
    }
}

Workflows

Gradual Adoption:
- Start with non-critical paths (e.g., logging, reporting).
- Replace custom implementations (e.g., manual clamping) with polyfill equivalents.
- Example: Replace a min/max helper function with clamp().
Dependency Management:
- Use composer why symfony/polyfill-php86 to audit usage.
- Pin the version in composer.json to avoid unexpected updates:
```
"symfony/polyfill-php86": "^1.38.0"
```

CI/CD Integration:

Test with and without the polyfill to simulate PHP 8.6 environments:

# .github/workflows/test.yml
jobs:
  test:
    strategy:
      matrix:
        php: [8.1, 8.5, 8.6]
    steps:
      - if: matrix.php == '8.6'
        run: composer remove symfony/polyfill-php86

Gotchas and Tips

Pitfalls

False Positives in Static Analysis:
- Tools like PHPStan or Psalm may flag polyfill functions as undefined if not configured.
- Fix: Add a phpstan.neon rule:
```
parameters:
    level: 5
    checkNativeFunctionImplementation: false
```
UTF-8 Handling in grapheme_strrev:
- The polyfill may mishandle invalid UTF-8 strings (e.g., emojis, CJK characters).
- Tip: Validate input before using:
```
if (mb_check_encoding($string, 'UTF-8')) {
    $reversed = grapheme_strrev($string);
}
```
Performance Overhead:
- Polyfills add ~5–10ms per call. Benchmark critical paths (e.g., loops with clamp()).
- Tip: Cache results if used frequently (e.g., in a service layer).

Redundancy in PHP 8.6+:

The polyfill becomes unnecessary once upgrading to PHP 8.6.

Tip: Use runtime checks to log warnings:

if (function_exists('clamp') && version_compare(PHP_VERSION, '8.6.0') >= 0) {
    Log::warning('Polyfill `clamp` is redundant in PHP 8.6+');
}

Enum Type Safety:

SortDirection may not be recognized by IDEs or static analyzers.

Fix: Add @method annotations in custom classes or use traits:

use Symfony\Polyfill\Php86\SortDirection;

class Sorter {
    public function sort(array $data, string $direction): array {
        return array_multisort($data, [SortDirection::from($direction)]);
    }
}

Debugging Tips

Verify Polyfill Loading: Check if functions are available at runtime:
```
dd(function_exists('clamp'), function_exists('grapheme_strrev'));
```

Edge Cases for clamp(): Test boundary conditions:

$this->assertEquals(10, clamp(5, 10, 20));      // Within bounds
$this->assertEquals(10, clamp(5, 10, 20));      // Below min
$this->assertEquals(20, clamp(25, 10, 20));     // Above max
$this->assertEquals(10, clamp(INF, 10, 20));    // Edge: INF

Array Filtering Quirks: ARRAY_FILTER_USE_VALUE may behave differently with associative arrays:

$assocArray = ['a' => 1, 'b' => 2];
$filtered = array_filter($assocArray, fn($v) => $v > 1, ARRAY_FILTER_USE_VALUE);
// Result: ['b' => 2]

Extension Points

Custom Polyfill Logic: Override polyfill behavior by extending the class:

class CustomClamp {
    public static function clamp($var, $min, $max) {
        // Custom logic (e.g., logging)
        return Symfony\Polyfill\Php86\clamp($var, $min, $max);
    }
}

Laravel Facades: Create a facade for polyfill functions to integrate seamlessly:

// app/Facades/Polyfill.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

class Polyfill extends Facade {
    protected static function getFacadeAccessor() {
        return 'polyfill';
    }
}

public function register() {
    $this->app->bind('polyfill', function () {
        return new class {
            public function clamp($var, $min, $max) {
                return \Symfony\Polyfill\Php86\clamp($var, $min, $max);
            }
        };
    });
}

Dynamic Loading: Lazy-load polyfills only when needed (e.g., in a service provider):

public function boot() {
    if (!function_exists('clamp') && version_compare(PHP_VERSION, '8.6.0') < 0) {
        require __DIR__.'/../../vendor/symfony/polyfill-php86/clamp.php';
    }
}

Config Quirks

Autoloading Issues: If functions aren’t recognized, clear Composer’s autoload cache:
```
composer dump-autoload
```
PHP Version Conflicts: Ensure your composer.json doesn’t enforce a PHP version that conflicts with

Polyfill Php86 Laravel Package