Blasp Laravel Package

Technical Evaluation

Architecture Fit

• Modular & Extensible: Driver-based architecture (regex, pattern, phonetic, pipeline) aligns with Laravel’s service provider pattern, enabling granular control over profanity detection. The fluent API and dependency injection (via Laravel’s container) ensure clean separation of concerns.
• Multi-Language Support: Language-specific normalizers and severity scoring provide flexibility for global applications or region-specific compliance (e.g., GDPR, platform-specific policies).
• Event-Driven: Integration with Laravel’s event system (ProfanityDetected, ModelProfanityDetected) enables reactive workflows (e.g., logging, analytics, or custom notifications).
• Cache Optimization: Configurable caching of results (by content hash) reduces redundant processing for repeated inputs (e.g., API responses, form submissions).

Integration Feasibility

• Laravel Native: Built for Laravel 8.0+ with Eloquent, middleware, validation, and Blade directives. Minimal boilerplate for core use cases (e.g., Blasp::check()).
• Validation Rules: Seamless integration with Laravel’s validation pipeline, reducing custom validation logic.
• Middleware: Pre-built CheckProfanity middleware handles request sanitization/rejection with configurable severity thresholds.
• Eloquent Trait: Blaspable trait automates model-level checks, ideal for comment systems, user-generated content, or moderation workflows.

Technical Risk

• Performance Overhead:
  • Regex Driver: Most computationally expensive (obfuscation detection). May impact high-throughput APIs or real-time systems (e.g., chat apps). Mitigate via caching or pipeline driver tuning.
  • Phonetic Driver: Metaphone + Levenshtein distance adds latency (~5–10ms per check). Benchmark under expected load.
• False Positives/Negatives:
  • Phonetic driver’s max_distance_ratio (default: 0.6) may misclassify slang or niche terms. Customize false_positives or extend the driver.
  • Language-specific dictionaries may lack coverage for regional slang (e.g., "bloody hell" in UK English). Supplement with custom allow/block lists.
• Configuration Complexity:
  • Pipeline driver requires tuning sub-drivers (e.g., regex + phonetic). Defaults may not suit all use cases (e.g., strict moderation vs. lenient forums).
  • Cache invalidation: Manual cache clearing may be needed for dynamic allow/block lists.
• Dependency Versioning:
  • Requires PHP 8.2+ and Laravel 8.0+. Ensure compatibility with existing stack (e.g., older Laravel versions or custom PHP extensions).

Key Questions

1. Use Case Alignment:
   • Is profanity detection needed for input validation (e.g., comments, messages), output sanitization (e.g., APIs, emails), or both?
   • Are there compliance requirements (e.g., GDPR, platform policies) dictating severity thresholds or masking strategies?
2. Performance Constraints:
   • What is the expected throughput (e.g., 1000 RPS)? Will the regex/phonetic drivers meet SLAs?
   • Can caching be enabled for repeated inputs (e.g., static API responses)?
3. Customization Needs:
   • Are custom drivers required (e.g., domain-specific slang, code words)?
   • Should allow/block lists be dynamically managed (e.g., via admin UI)?
4. Failure Modes:
   • How should false positives be handled (e.g., user appeals, manual overrides)?
   • What fallback behavior is needed if the profanity filter fails (e.g., graceful degradation)?
5. Testing Strategy:
   • How will obfuscation patterns (e.g., f-u-c-k, phuck) be tested in CI?
   • Are there edge cases (e.g., Unicode, mixed-language inputs) to validate?

Integration Approach

Stack Fit

• Laravel Ecosystem: Native support for Eloquent, validation, middleware, and Blade makes this a first-class citizen in Laravel apps. Minimal integration effort for core features.
• PHP 8.2+: Leverages modern PHP features (enums, attributes, named arguments) for cleaner code. No breaking changes for Laravel 8.0+.
• Composer Dependency: Single composer require with optional publishing for config/languages. No runtime dependencies beyond Laravel core.

Migration Path

1. Pilot Phase:
   • Validation-Only: Start with blasp_check validation rules for critical fields (e.g., comments, bios).
   • Middleware: Apply blasp:sanitize to API routes handling user-generated content.
   • Monitor: Track false positives/negatives and performance metrics (e.g., Blasp::check() execution time).
2. Full Integration:
   • Eloquent Models: Add Blaspable trait to models requiring sanitization (e.g., Post, Message).
   • Blade Directives: Replace manual str_replace() with @clean for safe output rendering.
   • Custom Drivers: Extend for niche use cases (e.g., CustomDriver for internal jargon).
3. Optimization:
   • Cache Tuning: Enable cache.results for high-frequency inputs (e.g., search queries).
   • Pipeline Tuning: Adjust drivers.pipeline to balance accuracy and performance (e.g., ['pattern', 'phonetic'] for speed).

Compatibility

• Laravel Versions: Tested on Laravel 8.0+. For Laravel 9/10, verify compatibility with updated service providers (e.g., Illuminate\Contracts\Container\BindingResolutionException).
• PHP Extensions: No hard dependencies, but metaphone (for phonetic driver) may require intl extension. Document requirements in composer.json.
• Database: No schema changes. Eloquent integration uses model attributes only.
• Third-Party Packages: Conflict risk with other profanity filters (e.g., spatie/laravel-profanity-filter). Audit dependencies for overlaps.

Sequencing

Operational Impact

Maintenance

• Configuration Management:
  • Publish blasp.php to customize defaults (e.g., languages, severity, masking).
  • Dynamic Updates: Allow/block lists can be updated via config or database (e.g., blasp_allow_list table). Implement a Blasp::syncAllowList() method if needed.
• Driver Updates:
  • Regex patterns may need updates for new obfuscation trends (e.g., f*ck). Monitor GitHub issues for pattern improvements.
  • Phonetic driver’s false_positives list may require maintenance for new slang.
• Dependency Updates:
  • Monitor for breaking changes in Laravel 11+ or PHP 8.3+. Test upgrades in staging.

Support

• Debugging:
  • Result Object: Detailed Result methods (uniqueWords(), words()) aid debugging. Log Blasp::check($text)->toArray() for troubleshooting.
  • Events: Subscribe to ProfanityDetected to log flagged content for review.
• User Feedback:
  • Provide a whitelist appeal process for false positives (e.g., admin dashboard to add words to allow list).
  • Expose Blasp::check()->score() to users for transparency (e.g., "This comment scored 85/100 for profanity").
• Documentation:
  • Internal runbook for:
    • Common obfuscation patterns (e.g., f-u-c-k).
    • Performance tuning (e.g., disabling phonetic driver for high-load routes).
    • Custom driver development.

Scaling

• Performance Bottlenecks:
  • Regex Driver: Offload to a queue (e.g., Laravel Queues) for non-critical paths (e.g., comment moderation).
  • Batch Processing: Use Blasp::checkMany() for bulk operations (e.g., importing user data).
  • Caching: Enable cache.results for repeated inputs (e.g., API responses,