Getting Started

Minimal Steps

Installation:
```
composer require joomla/filter "~3.0"
```
For PHP 8.3+ projects, use ~4.0 instead.

First Use Case: Sanitize user input in a Laravel controller or request handler:

use Joomla\Filter\InputFilter;

$cleanInput = InputFilter::clean(
    $userInput,
    InputFilter::ONLY_ALLOW_DEFINED_TAGS,
    ['p', 'b', 'i', 'a']
);

Where to Look First:
- InputFilter for HTML sanitization.
- OutputFilter for URL/string sanitization.
- Tests for edge-case examples (e.g., XSS evasion).

Implementation Patterns

Usage Patterns

Request Sanitization Pipeline:

// In a Laravel Form Request or middleware
public function sanitize($input, array $allowedTags = ['p', 'a'])
{
    return InputFilter::clean(
        $input,
        InputFilter::ONLY_ALLOW_DEFINED_TAGS,
        $allowedTags
    );
}

Service Provider Integration:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton('filter', function () {
        return new InputFilter();
    });
}

Inject via constructor:

public function __construct(private InputFilter $filter) {}

Dynamic Whitelists:

// Allow tags based on user role
$allowedTags = auth()->user()->role === 'admin' ? ['div', 'span'] : ['p', 'b'];
$cleanHtml = $this->filter->clean($input, InputFilter::ONLY_ALLOW_DEFINED_TAGS, $allowedTags);

Attribute-Level Control:

// Allow only href in <a> tags
$cleanHtml = InputFilter::clean(
    $input,
    InputFilter::ONLY_ALLOW_DEFINED_TAGS | InputFilter::ONLY_ALLOW_DEFINED_ATTRIBUTES,
    ['a'],
    ['href']
);

Workflows

Form Handling:

Use in validate() or sanitize() methods of Laravel Form Requests.

Example:

public function rules()
{
    return ['content' => 'required|string'];
}

public function sanitize($attribute, $value)
{
    return InputFilter::clean($value, InputFilter::ONLY_ALLOW_DEFINED_TAGS, ['p', 'b']);
}

API Payloads:

Sanitize JSON inputs before processing:

$data = json_decode($request->getContent(), true);
$data['description'] = InputFilter::clean($data['description'], ...);

CMS Content:

Integrate with Laravel Nova’s DetailPanel or custom fields:

// Nova Field
public function resolve($resource, $attribute)
{
    return InputFilter::clean($resource->$attribute, ...);
}

Integration Tips

Laravel Validation Rules: Extend Laravel’s validation with custom rules:

use Joomla\Filter\InputFilter;

class Sanitize extends FormRequest
{
    public function rules()
    {
        return ['bio' => ['required', new SanitizeRule(['p', 'a'])]];
    }
}

class SanitizeRule extends Rule
{
    public function __construct(private array $allowedTags)
    {
        parent::__construct();
    }

    public function passes($attribute, $value)
    {
        return InputFilter::clean($value, InputFilter::ONLY_ALLOW_DEFINED_TAGS, $this->allowedTags) !== false;
    }
}

Blade Directives: Create a custom Blade directive for sanitized output:

// app/Providers/BladeServiceProvider.php
Blade::directive('sanitize', function ($expression) {
    return "<?php echo InputFilter::clean({$expression}, InputFilter::ONLY_ALLOW_DEFINED_TAGS, ['p', 'b']); ?>";
});

Usage:

{!! sanitize($user->bio) !!}

Event Listeners: Sanitize data on model events (e.g., saving):

public function saving(Post $post)
{
    $post->content = InputFilter::clean(
        $post->content,
        InputFilter::ONLY_ALLOW_DEFINED_TAGS,
        ['h1', 'p', 'ul', 'li']
    );
}

Gotchas and Tips

Pitfalls

PHP Version Mismatch:
- v3.x: Requires PHP 8.1+.
- v4.x: Requires PHP 8.3+.
- Fix: Use ~3.0 for older Laravel projects (e.g., Laravel 9).
False Positives in Sanitization:
- Aggressive filtering may break legitimate HTML (e.g., <img src="..."> if src isn’t whitelisted).
- Fix: Test with real-world HTML snippets (e.g., from TinyMCE or CKEditor outputs).
Nested Tag Issues:
- Older versions (<3.0.2) had case-sensitivity bugs in stripImages/stripIframes.
- Fix: Upgrade to ~3.0.2 or later.
Attribute Filtering Quirks:
- ONLY_ALLOW_DEFINED_ATTRIBUTES can strip valid attributes if not configured carefully.
- Fix: Explicitly whitelist attributes (e.g., ['href', 'title'] for <a> tags).
Performance Overhead:
- Heavy filtering (e.g., large HTML blocks) may slow down requests.
- Fix: Cache sanitized results or use lazy loading for non-critical fields.

Debugging

Unexpected Output:

Use InputFilter::clean() with InputFilter::RETURN_ERRORS flag to debug:

$result = InputFilter::clean($input, InputFilter::RETURN_ERRORS, ['p']);
if ($result === false) {
    dd(InputFilter::getErrors()); // Inspect why sanitization failed
}

XSS Evasion Bypasses:
- Test with payloads like:
```
<script>alert(1)</script>
<img src=x onerror=alert(1)>
<a href="javascript:alert(1)">Click</a>
```
- Fix: Ensure ~4.0.1+ (removes common evasion chars) or manually add rules.

Whitelist Misconfigurations:

Verify allowed tags/attributes with:

$config = InputFilter::getConfig();
dd($config->allowedTags, $config->allowedAttributes);

Config Quirks

Static vs. Instance Methods:
- Static methods (e.g., InputFilter::clean()) use global config.
- Instance methods allow per-object customization:
```
$filter = new InputFilter();
$filter->setAllowedTags(['div', 'span']);
$clean = $filter->clean($input);
```
OutputFilter Dependencies:
- OutputFilter::stringURLSafe() requires joomla/language package.
- Fix: Install via Composer if needed:
```
composer require joomla/language
```
Legacy Constant Names:
- Older code may use deprecated constants (e.g., TAGS_WHITELIST).
- Fix: Update to new names (e.g., ONLY_ALLOW_DEFINED_TAGS).

Extension Points

Custom Filters: Extend InputFilter to add domain-specific rules:

class CustomFilter extends InputFilter
{
    public function cleanCustom($input)
    {
        return $this->clean($input, InputFilter::ONLY_ALLOW_DEFINED_TAGS, ['custom']);
    }
}

Event-Driven Sanitization: Use Laravel events to trigger sanitization:

// In a service provider
event(new SanitizeEvent($input));

Handle with a listener:

public function handle(SanitizeEvent $event)
{
    $event->setSanitized(InputFilter::clean($event->input, ...));
}

Testing Helpers: Create a test

Filter Laravel Package