Getting Started

Installation: Add the package via Composer:
```
composer require symfony/polyfill-php82
```
No additional configuration is required—it auto-registers via Composer’s autoloader.
First Use Case: Use PHP 8.2+ runtime features (e.g., JSON_THROW_ON_ERROR, FILTER_VALIDATE_BOOL, or odbc_connection_string_quote()) in your Laravel code without version checks. The polyfill handles compatibility transparently.
Verification: Test on your target PHP versions (e.g., 7.4, 8.0, 8.1) to ensure features like:
- json_encode($data, JSON_THROW_ON_ERROR)
- filter_var($input, FILTER_VALIDATE_BOOL)
- mb_str_split($string, 1, 'UTF-8') work as expected.

Implementation Patterns

1. Modern Code Without Version Guards

Write Laravel logic using PHP 8.2+ features directly. Example:

// In a Laravel service or controller
$json = json_encode($data, JSON_THROW_ON_ERROR); // Works on PHP <8.2
$isValid = filter_var($input, FILTER_VALIDATE_BOOL); // Polyfilled constant

2. Library Development

If your package uses PHP 8.2+ runtime features but targets older PHP:

// composer.json
"require": {
    "symfony/polyfill-php82": "^1.38"
}

This ensures downstream users get compatibility automatically.

3. Framework Integration

Leverage polyfilled features in:

Services: Use Random\Engine\Secure for cryptographic operations.
Jobs/Queues: Pass sensitive parameters with @SensitiveParameter (if using Symfony components).
Middleware: Validate inputs with FILTER_VALIDATE_BOOL or ini_parse_quantity().

4. ODBC/INI Features

For legacy systems:

$quoted = odbc_connection_string_quote($connectionString); // Polyfilled
$quantity = ini_parse_quantity('100%', INI_ALL); // Works on older PHP

5. Testing

Use PHPUnit to validate behavior across versions:

public function testJsonThrowOnError() {
    $this->expectException(JsonException::class);
    json_encode([], JSON_THROW_ON_ERROR);
}

Gotchas and Tips

1. Syntax vs. Runtime Features

Not Polyfilled: Syntax like readonly properties, true typehints, or enum will fail on PHP <8.2. Verify your code’s minimum PHP version supports all syntax.

Example: This will not work on PHP 7.4:

class User {
    public function __construct(public readonly string $name) {} // Fails
}

2. Zero Overhead on Modern PHP

On PHP ≥8.2, the package does nothing—no performance impact or conflicts.

3. Debugging Polyfill Issues

Symptom: Polyfilled feature throws a generic error (e.g., JSON_THROW_ON_ERROR fails). Fix:
1. Confirm symfony/polyfill-php82 is installed:
```
composer show symfony/polyfill-php82
```
2. Check if the polyfill is loaded (look for symfony/polyfill in phpinfo()).
3. Clear OPcache:
```
php artisan cache:clear
```

4. Avoid Manual Overrides

Never edit polyfill files directly. If behavior differs, wrap the function in your own class:

// app/Helpers/PolyfillHelper.php
class PolyfillHelper {
    public static function safeJsonEncode($data, int $flags = 0) {
        return json_encode($data, $flags);
    }
}

5. Edge Cases

Random\Engine: For advanced use cases (e.g., custom engines), consider arokettu/random-polyfill.
ODBC Functions: Test with non-ASCII inputs for odbc_connection_string_* functions.
INI Parsing: ini_parse_quantity() may behave differently for malformed strings.

6. Testing Across PHP Versions

Use Laravel’s phpunit.xml to test multiple PHP versions:

<php>
    <env name="APP_ENV" value="testing"/>
    <env name="DB_CONNECTION" value="sqlite_memory"/>
    <ini name="memory_limit" value="1024M"/>
</php>

Run tests with:

sail test --php=7.4
sail test --php=8.0

7. Composer Autoloading

Ensure vendor/autoload.php is loaded (Laravel handles this by default).
If using custom autoloading, verify the polyfill’s composer.json autoload section is included.

8. Conflicts with Custom Polyfills

If you’ve manually polyfilled a feature (e.g., JSON_THROW_ON_ERROR), remove the custom implementation to avoid conflicts. The Symfony polyfill takes precedence.

Polyfill Php82 Laravel Package