Purify Laravel Package

Product Decisions This Supports

• Security & Compliance:

  • Enables safe handling of user-generated HTML content (e.g., comments, rich-text editors like Trix, or CMS content) by stripping malicious scripts (XSS, SQLi, etc.) while preserving intended formatting.
  • Aligns with OWASP guidelines for input validation/sanitization, reducing attack surface for web applications.

• Rich-Text Editor Integration:

  • Supports WYSIWYG editors (e.g., Trix, CKEditor, Quill) by allowing custom HTML definitions (e.g., <figure>, <figcaption> for Trix attachments).
  • Reduces friction for teams using rich-text fields by balancing security with functionality (e.g., preserving editor-specific attributes like data-trix-*).

• Multi-Tenant or Role-Based Sanitization:

  • Configurable profiles (e.g., comments, admin_posts) let PMs enforce stricter rules for sensitive content (e.g., admin dashboards) vs. public-facing areas.
  • Example: Allow <iframe> in admin panels but block it in user comments.

• Performance Optimization:

  • Built-in caching (via Laravel’s cache or filesystem) reduces runtime overhead for repeated purifications (critical for high-traffic sites).
  • "Sanitize on output" pattern (via Eloquent casts) shifts processing to read operations, avoiding redundant work during writes.

• Roadmap: AI-Generated Content:

  • Future-proofs for AI-generated HTML (e.g., LLMs outputting markdown/HTML) by providing granular control over allowed tags/attributes.
  • Example: Block <script> but allow <div> with data-* attributes for structured data.

• Build vs. Buy:

  • Buy: Avoids reinventing HTML sanitization (a complex, error-prone task). Leverages battle-tested HTMLPurifier under the hood.
  • Build: Only consider if needing highly custom sanitization (e.g., domain-specific languages) not covered by HTMLPurifier’s extensibility.

When to Consider This Package

Adopt This Package If:

• Your app accepts user-generated HTML (comments, forums, CMS, rich-text fields) and requires XSS protection.
• You use Laravel and want a seamless integration (facades, Eloquent casts, config-driven).
• You need fine-grained control over allowed HTML/CSS (e.g., whitelisting specific tags like <figure> for Trix).
• Your team prioritizes security over flexibility (e.g., blocking all scripts by default).
• You’re using rich-text editors (Trix, CKEditor) and need to preserve editor-specific attributes while sanitizing.

Look Elsewhere If:

• You don’t use Laravel (this is a Laravel-specific wrapper; use HTMLPurifier directly).
• Your use case is non-HTML (e.g., sanitizing URLs, SQL, or plain text—use dedicated packages like str or sanitize-html).
• You need real-time sanitization (e.g., live preview) and caching adds latency (disable caching or use a lighter alternative like htmlentities for simple cases).
• Your HTML requirements are extremely permissive (e.g., allowing arbitrary <script> tags with CSP as the primary defense).
• You’re building a headless CMS where HTML is processed server-side only (may not need client-side sanitization).

How to Pitch It (Stakeholders)

For Executives (Business Impact)

"This package lets us safely enable user-generated content—like rich-text comments or WYSIWYG editors—without exposing our app to XSS attacks. It’s like a ‘security firewall’ for HTML, automatically stripping malicious scripts while preserving the formatting users intend. For example, we can let customers use Trix for polished content in our support portal, but block any embedded JavaScript that could hijack sessions. It’s a low-code solution that reduces our attack surface while keeping the UX rich. The caching feature also ensures it won’t slow down high-traffic areas like our blog or forum."

Key Metrics to Track:

• Reduction in XSS vulnerabilities (via security scans).
• Improved UX for content creators (e.g., faster load times with cached purifications).
• Cost avoidance (no custom dev time for sanitization logic).

For Engineers (Technical Value)

*"This is a Laravel-native wrapper for HTMLPurifier, giving us enterprise-grade HTML sanitization with zero reinvention. Key perks:

• Seamless integration: Works with facades (Purify::clean()), Eloquent casts (PurifyHtmlOnGet), and config-driven profiles.
• Extensible: Customize allowed tags/attributes (e.g., support Trix’s <figure> tags) via PHP classes. Need to allow data-* attributes? Done in 10 lines.
• Performance: Caches purifier definitions by default (configurable to filesystem/Laravel cache). Clear cache via php artisan purify:clear.
• Best practices baked in: Follows ‘sanitize on output’ (not input) to avoid DB bloat, with built-in Eloquent support.
• Future-proof: Handles edge cases like HTML5 doctypes and custom CSS properties (e.g., text-align: start).*

Trade-offs:

• Adds ~1MB to your vendor dir (HTMLPurifier dependency).
• Requires config tweaks for complex use cases (e.g., multi-profile sanitization).

Alternatives considered:

• sanitize-html: Lighter but less configurable for Laravel.
• Custom regex/strip_tags: Risky (false positives/negatives).
• HTMLPurifier raw: More control but no Laravel integration.

Recommendation: Use this for any user-generated HTML in Laravel. Pair with CSP for defense-in-depth."*

For PMs (Implementation Notes):

• Quick win: Start with default config for basic XSS protection.
• Advanced: Use PurifyHtmlOnGet cast for Eloquent models to auto-sanitize on retrieval.
• Editor support: Add a TrixPurifierDefinitions class if using Trix (example in README).
• Monitor: Log purifications that strip content (e.g., if (strlen($cleaned) < strlen($dirty)) log->warning(...)) to catch false positives.