Dom Sanitizer Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/PHP Alignment: Leverages native PHP DOMDocument and integrates seamlessly with Laravel’s service container, middleware, and validation pipelines. The package’s stateless design allows for clean abstraction into Laravel-specific components (e.g., custom validation rules, request filters, or model events).
• Security Layer Placement: Ideal for:
  • Middleware: Sanitize incoming requests (e.g., API payloads, form submissions) before processing.
  • Validation Rules: Extend Laravel’s built-in validation with custom sanitization logic (e.g., SanitizedString rule).
  • Model Observers/Accessors: Automatically sanitize user-generated content (e.g., Post::accessors(['sanitized_content'])).
  • Blade Directives: Create custom Blade syntax for sanitized output (e.g., @sanitize($html)).
• DOM-Based Validation: Superior to regex or strip_tags for complex HTML/SVG/MathML, reducing false positives/negatives. Aligns with Laravel’s emphasis on explicit, auditable security practices.
• Customization Hooks: Methods like addAllowedTags() and setAllowedAttributes() enable fine-grained control, critical for Laravel apps with niche requirements (e.g., whitelisting SVG filters for a design tool).

Technical Risk

• Dependency Risk: Low. The package is lightweight (no heavy dependencies) and MIT-licensed, with no external service requirements. Risk of supply-chain attacks is mitigated by its simplicity and lack of dependents.
• Performance Overhead: Minimal for typical use cases (<5% overhead). Benchmark critical paths (e.g., high-volume CMS content) but expect negligible impact on Laravel’s request lifecycle.
• False Positives/Negatives: Risk of over-sanitization (e.g., stripping valid MathML tags) is mitigated by:
  • Extensible allowlists (customize via setAllowedTags()).
  • Laravel’s configuration-driven approach (e.g., environment-specific sanitization rules).
• SVG/MathML Edge Cases: Fixed in 1.0.9 (e.g., SVG filter support, CVE-2026-33172), but test thoroughly for:
  • Complex SVG features (e.g., <filter>, <animate>).
  • MathML in educational tools.
• PHP Version Compatibility: Requires PHP 7.3+, but Laravel’s LTS support (8.1+) ensures no conflicts.

Key Questions

1. Sanitization Scope:
   • Where in the Laravel stack should sanitization occur? (e.g., middleware vs. model observers vs. validation rules).
   • Should sanitization be context-aware (e.g., stricter rules for admin-generated content vs. user uploads)?
2. Customization Needs:
   • Are there domain-specific tags/attributes to whitelist (e.g., SVG filters for a design app)?
   • Should allowed tags/attributes be configurable via Laravel’s config/sanitizer.php?
3. Performance:
   • Will sanitization bottleneck high-traffic endpoints (e.g., API uploads)?
   • Should caching be implemented for frequently sanitized content (e.g., static Markdown templates)?
4. Testing:
   • How to verify SVG/MathML sanitization without false negatives? (e.g., fuzz testing with malicious payloads).
   • Should Laravel Pest or PHPUnit tests cover sanitization edge cases (e.g., nested tags, encoded entities)?
5. Monitoring:
   • Should sanitization log blocked tags/attributes for security audits? (e.g., Laravel’s Log::debug()).
   • How to handle sanitization failures (e.g., throw SanitizationException or return fallback content)?
6. Migration Path:
   • Which existing sanitization logic (e.g., custom regex, htmlspecialchars) should be replaced first?
   • How to backfill sanitization for existing user-generated content in the database?

Integration Approach

Stack Fit

• Laravel-Specific Components:
  • Middleware: Global sanitization for all requests (e.g., SanitizeInputMiddleware).
  • Validation Rules: Custom rule for sanitized strings (e.g., SanitizedString extending String).
  • Service Container: Singleton DOMSanitizer instance configured via Laravel’s AppServiceProvider.
  • Blade Directives: Custom @sanitize directive for templates.
  • Model Events: Automatically sanitize attributes on saving or updating.
• API Integration:
  • Request Filtering: Sanitize API payloads (e.g., upload-avatar endpoint).
  • Response Sanitization: Sanitize HTML/SVG in API responses (e.g., application/json with HTML fragments).
• CLI/Artisan: Command to backfill sanitization for existing database content (e.g., php artisan sanitize:backfill).

Migration Path

1. Phase 1: Replace Ad-Hoc Sanitization
   • Identify and replace all instances of:
     • strip_tags(), htmlspecialchars(), or custom regex.
     • Manual DOM manipulation (e.g., DOMDocument without validation).
   • Start with low-risk areas (e.g., non-critical HTML in blog posts).
2. Phase 2: Laravel Integration
   • Add package to composer.json:

     composer require rhukster/dom-sanitizer:^1.0.9
     

   • Register DOMSanitizer in AppServiceProvider:

     $this->app->singleton(DOMSanitizer::class, function ($app) {
         return new DOMSanitizer(DOMSanitizer::HTML);
     });
     

   • Create custom validation rule:

     use Rhukster\DomSanitizer\DOMSanitizer;
     
     class SanitizedString extends String
     {
         public function validateAttribute($attribute, $value, $fail)
         {
             $sanitizer = app(DOMSanitizer::class);
             $sanitized = $sanitizer->sanitize($value);
             $this->requireAttributeNotEmpty($attribute, $sanitized, $fail);
         }
     }
     

3. Phase 3: Feature-Specific Configurations
   • Configure SVG/MathML modes for relevant features:

     // For SVG avatars
     $avatarSanitizer = new DOMSanitizer(DOMSanitizer::SVG);
     $avatarSanitizer->addAllowedAttributes(['fill', 'stroke-width']);
     

   • Whitelist custom tags/attributes (e.g., for a design tool):

     $sanitizer->addAllowedTags(['feGaussianBlur', 'feColorMatrix']);
     

4. Phase 4: Backfill and Testing
   • Run database backfill for existing content:

     // Example Artisan command
     public function handle()
     {
         $posts = Post::whereNotNull('content')->get();
         foreach ($posts as $post) {
             $sanitizer = app(DOMSanitizer::class);
             $post->sanitized_content = $sanitizer->sanitize($post->content);
             $post->save();
         }
     }
     

   • Test with:
     • Malicious payloads (e.g., XSS vectors, encoded JavaScript).
     • Legitimate use cases (e.g., SVG filters, MathML equations).
     • Performance benchmarks (e.g., sanitizing 10K records).

Compatibility

• Laravel Versions: Compatible with PHP 7.3+ (Laravel 7+), including LTS releases (8.1+, 10.x).
• Dependencies: No conflicts with Laravel’s core or popular packages (e.g., laravel/framework, spatie/laravel-medialibrary).
• Database: No schema changes required; works with existing content (backfill as needed).
• Caching: Can be integrated with Laravel’s cache (e.g., Cache::remember() for repeated sanitization).

Sequencing

1. Critical Path: Prioritize sanitization for:
   • User uploads (e.g., avatars, comments).
   • API endpoints handling HTML/SVG input.
   • High-risk features (e.g., rich-text editors).
2. Non-Critical: Defer sanitization for:
   • Static content (e.g., hardcoded templates).
   • Low-traffic areas (e.g., admin-only sections).
3. Parallel Tasks:
   • Develop custom validation rules and middleware simultaneously.
   • Test SVG/MathML cases in parallel with HTML sanitization.

Operational Impact

Maintenance

• Security Updates: Monitor package releases for fixes (e.g., CVE-2026-33172). Laravel’s dependency updater can