Getting Started

Minimal Steps

Installation: Add the package via Composer in your Laravel project:
```
composer require symfony/polyfill-ctype
```
No additional configuration is required—Laravel’s autoloader will handle the rest.

First Use Case: Replace any ctype_* function calls (e.g., ctype_alnum(), ctype_digit()) in your code. The polyfill will automatically provide the functionality if the native ctype extension is unavailable.

// Before (may fail if ctype extension is missing)
if (ctype_alnum($input)) {
    // Process alphanumeric input
}

// After (works everywhere)
if (\Symfony\Component\Polyfill\Ctype\Ctype::isAlnum($input)) {
    // Process alphanumeric input
}

Alternatively, use the global functions (if the polyfill is loaded):

if (ctype_alnum($input)) { // Now works due to polyfill
    // Process input
}

Verify Functionality: Test in an environment where the ctype extension is disabled (e.g., a Docker container without the extension) to confirm the polyfill works as expected.

Implementation Patterns

Usage Patterns

Validation in Laravel: Use the polyfill in custom validation rules or FormRequest classes:

use Symfony\Component\Polyfill\Ctype\Ctype;

public function rules()
{
    return [
        'username' => ['required', 'string', function ($attribute, $value, $fail) {
            if (!Ctype::isAlnum($value)) {
                $fail('The '.$attribute.' must contain only alphanumeric characters.');
            }
        }],
    ];
}

Middleware for Input Sanitization: Sanitize input in middleware by stripping non-alphanumeric characters:

use Symfony\Component\Polyfill\Ctype\Ctype;

public function handle($request, Closure $next)
{
    $input = $request->input('query');
    if (!Ctype::isAlnum($input)) {
        $sanitized = preg_replace('/[^a-zA-Z0-9]/', '', $input);
        $request->merge(['query' => $sanitized]);
    }
    return $next($request);
}

Slug Generation: Ensure slugs are alphanumeric before generating:

use Symfony\Component\Polyfill\Ctype\Ctype;
use Illuminate\Support\Str;

$title = "Hello World 123!";
$slug = Ctype::isAlnum($title)
    ? Str::slug($title)
    : Str::slug(preg_replace('/[^a-zA-Z0-9]/', '', $title));

API Input Validation: Validate API keys or tokens using ctype_* functions:

use Symfony\Component\Polyfill\Ctype\Ctype;

public function validateToken($token)
{
    return Ctype::isAlnum($token) && strlen($token) === 32;
}

Workflows

Conditional Logic Replacement: Replace conditional checks for ctype_* function existence:

// Before (verbose)
if (function_exists('ctype_alnum') && ctype_alnum($input)) {
    // Process
}

// After (simplified)
if (\Symfony\Component\Polyfill\Ctype\Ctype::isAlnum($input)) {
    // Process
}

Testing: Write tests to verify ctype_* behavior across environments:

use Symfony\Component\Polyfill\Ctype\Ctype;
use PHPUnit\Framework\TestCase;

class CtypePolyfillTest extends TestCase
{
    public function testAlnumValidation()
    {
        $this->assertTrue(Ctype::isAlnum('abc123'));
        $this->assertFalse(Ctype::isAlnum('abc@123'));
    }
}

CI/CD Integration: Ensure tests pass in environments where the ctype extension is disabled (e.g., Docker containers in CI):

# .github/workflows/tests.yml
jobs:
  test:
    runs-on: ubuntu-latest
    container: php:8.1-cli
    steps:
      - run: docker-php-ext-disable ctype
      - run: composer install
      - run: composer test

Integration Tips

Leverage Laravel’s Str Helper: Combine with Laravel’s Str helper for cleaner code:

use Symfony\Component\Polyfill\Ctype\Ctype;
use Illuminate\Support\Str;

$input = "Hello123!";
$sanitized = Ctype::isAlnum($input)
    ? $input
    : Str::of($input)->replaceMatches('/[^a-zA-Z0-9]/', '');

Custom Validation Rules: Create reusable validation rules:

use Illuminate\Contracts\Validation\Rule;
use Symfony\Component\Polyfill\Ctype\Ctype;

class AlnumRule implements Rule
{
    public function passes($attribute, $value)
    {
        return Ctype::isAlnum($value);
    }

    public function message()
    {
        return 'The :attribute must contain only alphanumeric characters.';
    }
}

Usage:

'username' => ['required', new AlnumRule],

Service Providers: Register the polyfill globally in AppServiceProvider if needed (though not required):

use Symfony\Component\Polyfill\Ctype\Ctype;

public function boot()
{
    if (!extension_loaded('ctype')) {
        Ctype::boot();
    }
}

Gotchas and Tips

Pitfalls

Deprecation Warnings in PHP 8.1+:
- The polyfill may trigger E_DEPRECATED warnings for ctype_* functions in PHP 8.1+. Suppress warnings globally in bootstrap/app.php:
```
error_reporting(E_ALL & ~E_DEPRECATED);
```
- Alternatively, replace ctype_* with preg_match or mb_* in critical paths.
Unicode Limitations:
- The polyfill only supports ASCII. For Unicode validation (e.g., café), use mb_ctype_alnum() or Laravel’s Str::isAlphanumeric():
```
if (mb_ctype_alnum($input, 'UTF-8')) {
    // Unicode-safe validation
}
```
Performance Overhead:
- The polyfill is ~2–3x slower than native ctype. Benchmark critical paths (e.g., API rate-limiting) and optimize with native extensions where possible.
Global Function Override:
- The polyfill may override global ctype_* functions. If this causes conflicts, use the fully qualified class name:
```
\Symfony\Component\Polyfill\Ctype\Ctype::isAlnum($input);
```
Transitive Dependencies:
- Ensure no existing Symfony polyfills conflict with this package. Run:
```
composer why symfony/polyfill-ctype
```

Debugging

Check Extension Availability: Verify if the ctype extension is loaded:

if (extension_loaded('ctype')) {
    echo "Native ctype extension is available.";
} else {
    echo "Using polyfill for ctype functions.";
}

Debug Deprecation Warnings: Use Laravel’s exception handler to log deprecation warnings:

// In App\Exceptions\Handler
public function report(Throwable $exception)
{
    if ($exception instanceof ErrorException && $exception->getSeverity() === E_DEPRECATED) {
        Log::warning('Deprecated ctype function used: ' . $exception->getMessage());
    }
}

Test Edge Cases: Test edge cases like empty strings, non-string inputs, or mixed-case inputs:

$this->assertFalse(Ctype::isAlnum(''));
$this->assertFalse(Ctype::isAlnum(123));
$this->assertTrue(Ctype::isAlnum('ABC123'));

Tips

Prefer Str::isAlphanumeric(): For new code, prefer Laravel’s Str::isAlphanumeric() (Unicode-safe) over ctype_alnum:
```
use Illuminate\Support\Str;

if (Str::isAlphanumeric($input)) {
    // Unicode and ASCII support
}
```
Use Fully Qualified Names: Avoid ambiguity by using fully qualified names in critical code:
```
\Symfony\Component\Polyfill\Ctype\Ctype::isAlnum($input);
```
Document Assumptions: Document where ctype_* functions are used and whether ASCII-only validation is acceptable:

Polyfill Ctype Laravel Package