Htmlawed Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment (Updated)

  • Enhanced HTML5 Compliance: The new release (v1.3.4) introduces critical HTML5 semantic improvements:
    • <details> Element Support: PR #19 allows flow content (e.g., <summary>, <p>) inside <details>, aligning with modern web standards. This is a game-changer for Laravel apps using collapsible sections (e.g., FAQs, accordions).
    • Self-Closing Tag Handling: PR #18 neutralizes or removes illegal self-closing tags (e.g., <img/>, <br/>), reducing XSS risks in malformed HTML. This is proactive security for user-generated content.
  • Upstream Sync: Update to kesar/HTMLawed v1.2.15 (PR #17) suggests ongoing maintenance, though contributor activity (@Kdecherf, @j0k3r) remains limited to 2 developers.

• Laravel-Specific Synergy

  • Blade/Validation Integration:
    • <details> Support: Enable rich interactive content in Blade templates without escaping:

      <details>
          <summary>Click for details</summary>
          <p>{{ $htmlawed->sanitize($userComment) }}</p>
      </details>
      

    • Self-Closing Tag Fix: Mitigates edge cases in legacy HTML imports (e.g., <img/> from old CMS exports).
  • Validation Rules: Extend custom rules to leverage <details> and stricter tag validation:

    Rule::macro('sanitized_html', function (array $allowedTags = ['details', 'summary']) {
        // ...
    });
    

Integration Feasibility

• Backward Compatibility

  • No Breaking Changes: All PRs are feature/bugfix-only:
    • PR #18 (#19) are additive (no API changes).
    • PR #20 (GitHub Actions) is infrastructure-only.
  • Configuration Impact:
    • New Allowed Tags: Explicitly whitelist <details> and <summary> if used:

      $htmlawed->allowTags(['details', 'summary']);
      

    • Self-Closing Tag Behavior: Now default-denies invalid tags (e.g., <img/>), which may require updating existing whitelists.

• Laravel 11+ Readiness

  • PHP 8.3+: Test for compatibility with new PHP features (e.g., typed class constants) in the upstream kesar/HTMLawed v1.2.15.
  • Middleware: Update to handle <details>-related attributes (e.g., open):

    $htmlawed->allowAttributes(['details' => ['open']]);
    

Technical Risk

• Maintenance Risk (Reduced)

  • Dual Contributor Activity: PRs from @j0k3r (new contributor) suggest growing community interest, but still no formal governance.
  • Fork Risk: Monitor for upstream kesar/HTMLawed stalls (last release: 2021). Mitigate by:
    • Forking Strategy: Prepare a private fork if @Kdecherf’s activity drops.
    • Dependency Lock: Pin fossar/htmlawed to ^1.3.4 in composer.json to avoid auto-updates.

• Functional Risk (Low)

  • Self-Closing Tag Handling: May break existing HTML with invalid tags (e.g., <br/>). Audit:
    • Legacy Imports: Test with historical HTML (e.g., from database migrations).
    • User-Generated Content: Log sanitization failures for <img/> or <br/> tags.
  • <details> Quirks: Ensure nested content (e.g., <details><p>{{ $unsafe }}</p></details>) doesn’t trigger false positives.

• Security Risk (Improved)

  • Self-Closing Tag Neutralization: PR #18 reduces XSS vectors from malformed tags, but:
    • Test Edge Cases: Verify handling of <script/> or <iframe/> (should still be blocked).
    • SVG Risks: Confirm <svg/> tags are not allowed by default (they should be explicitly whitelisted).
  • <details> Security: Ensure no event handlers (e.g., ondetailschange) are accidentally allowed.

Key Questions (Updated)

1. HTML5 Compatibility Needs

   • Does your app use <details>/<summary> for interactive content? If yes, this release directly enables it.
   • Are you processing legacy HTML with self-closing tags (e.g., <img/>)? Plan for sanitization failures during migration.

2. Validation Rule Updates

   • Update Laravel’s sanitized_html macro to include:

     $htmlawed->allowTags(['details', 'summary']);
     $htmlawed->allowAttributes(['details' => ['open']]);
     

   • Test with nested structures:

     <details>
         <summary>Nested Example</summary>
         <p>{{ $userInput }}</p>
     </details>
     

3. Legacy HTML Migration

   • Pre-Migration Audit: Run a query to find invalid self-closing tags in your database:

     SELECT * FROM posts WHERE content LIKE '%<img/%' OR content LIKE '%<br/%';
     

   • Fallback Plan: Implement a pre-sanitization step to normalize tags:

     $content = str_replace(['<img/', '<br/'], ['<img ', '<br>'], $content);
     

4. Performance Impact

   • Benchmark <details> parsing in high-volume contexts (e.g., 10K+ comments). Use Laravel’s bench():

     $htmlawed->bench(function () {
         $htmlawed->sanitize($largeHtmlString);
     });
     

5. Long-Term Viability

   • Contributor Engagement: Propose a maintenance agreement with @Kdecherf or @j0k3r for critical updates.
   • Alternative Evaluation: If risk is unacceptable, compare with:
     • Laravel 11’s sanitizeHtml(): Now supports <details> but lacks attribute control.
     • DOMPurifier: Overkill for most Laravel apps but offers enterprise-grade sanitization.

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem (Expanded)

  • Ideal For:
    • Interactive Content: Apps using <details>/<summary> (e.g., documentation, FAQs).
    • Legacy HTML Cleanup: Projects migrating from XHTML-style self-closing tags to HTML5.
    • Security-Conscious Apps: Organizations prioritizing strict tag validation (e.g., financial, healthcare).
  • Avoid For:
    • Static Content: If your app only uses <p>, <a>, and <img> (no <details>), the benefits are marginal.
    • High-Velocity Environments: The self-closing tag normalization adds minor overhead (~5% based on anecdotal benchmarks).

• Dependency Synergy

  • Laravel Validation:
    • Extend sanitized_html rule to support <details>:

      Rule::macro('sanitized_html', function (array $allowedTags = ['details', 'summary']) {
          $htmlawed = new \htmlawed\HTMLawed();
          $htmlawed->allowTags($allowedTags);
          return function ($attribute, $value, $fail) use ($htmlawed) {
              if ($htmlawed->sanitize($value) !== $value) {
                  $fail("The {$attribute} field contains unsafe HTML.");
              }
          };
      });
      

  • Blade Directives:
    • Create a custom directive for <details>-safe content:

      Blade::directive('details', function ($expression) {
          return "<?php echo (new \htmlawed\HTMLawed())->sanitize({$expression}); ?>";
      });
      

      Usage:

      @details($userComment)
      

Migration Path

1. Pilot: <details> Support

   • Step 1: Whitelist <details> and <summary> in a non-critical section (e.g., blog footer FAQ):

     $htmlawed = new \htmlawed\HTMLawed();
     $htmlawed->allowTags(['details', 'summary']);
     $htmlawed->allowAttributes(['details' => ['open']]);
     

   • Step 2: Test with static content (no user input) to validate rendering.

2. **Phase 2: Self-Cl