Blasp Laravel Package

Technical Evaluation

Architecture Fit

• Modular Design: The driver-based architecture (regex, pattern, phonetic, pipeline) aligns well with Laravel’s extensibility, allowing TPMs to customize detection logic without monolithic refactoring. The pipeline driver (chaining multiple drivers) is particularly valuable for balancing precision and performance.
• Severity Scoring: The 0–100 severity system enables granular control (e.g., blocking only "high" profanity in public forums while allowing "mild" in moderated spaces). This maps cleanly to Laravel’s validation and middleware layers.
• Event-Driven: Integration with Laravel’s event system (ProfanityDetected, ModelProfanityDetected) allows for observability and side effects (e.g., logging, analytics) without polluting business logic.
• API Consistency: The fluent API (Blasp::check()->mask()->in('spanish')) mirrors Laravel’s query builder and validation patterns, reducing cognitive load for developers.

Integration Feasibility

• Laravel Native: Built for Laravel 8.0+ with Eloquent traits, middleware, validation rules, and Blade directives. Minimal boilerplate for core use cases (e.g., @clean($text) in views).
• Hybrid Cloud/API: Supports both self-hosted (via package) and cloud-based (blasp.app) modes. The cloud option reduces maintenance but introduces dependency on external services.
• Language Support: Out-of-the-box for English, Spanish, German, French, with extensibility for custom languages via published language files.

Technical Risk

• Performance Overhead:
  • Regex Driver: Most accurate but computationally expensive (obfuscation detection). Risk of latency spikes in high-throughput systems (e.g., comment sections).
  • Phonetic Driver: Uses metaphone() + Levenshtein distance, which can be slow for short words. Configure min_word_length to mitigate.
  • Pipeline Driver: Chaining drivers (e.g., regex + phonetic) compounds cost. Benchmark in staging before production.
• False Positives/Negatives:
  • Phonetic Driver: May flag innocuous words (e.g., "fork" → "fuck"). Mitigate via false_positives config or allow() lists.
  • Regex Driver: Separator limits (3 chars max) may miss creative obfuscation (e.g., f-u-u-u-c-k). Extend with custom drivers if needed.
• State Management:
  • Cache: Results can be cached by content hash (cache.results: true), but invalidation requires manual handling for dynamic content.
  • Middleware: Global blasp middleware applies to all routes by default. Explicitly exclude sensitive endpoints (e.g., /admin) to avoid unintended blocking.
• Dependency on External API:
  • Cloud mode (blasp.app) introduces network latency and uptime risk. Self-hosted mode avoids this but requires manual updates to word lists.

Key Questions for TPM

1. Performance Requirements:
   • What’s the expected throughput for profanity checks (e.g., 10K requests/min)? Will the regex driver be viable, or should we default to pattern + phonetic?
   • Should we pre-warm caches for high-traffic endpoints (e.g., trending comments)?
2. Accuracy vs. Speed Tradeoffs:
   • Is precision (catching obfuscated words) more critical than speed? If not, prioritize the pattern driver for most checks.
   • Should we disable the phonetic driver for languages where it’s less effective (e.g., non-English)?
3. Deployment Strategy:
   • Will we use self-hosted or cloud mode? If cloud, what’s the fallback plan for API downtime?
   • How often will we update word lists? Automate via composer update or integrate with a moderation API?
4. User Experience:
   • Should profanity be masked (****) or rejected (422 error)? Context-dependent (e.g., reject in public forums, mask in moderated spaces).
   • How will we communicate blocks to users? Custom error messages or redirects?
5. Extensibility:
   • Are there custom drivers needed (e.g., for emoji profanity, code snippets)? Plan for a driver registry pattern.
   • Should we expose a public API for third-party integrations (e.g., mobile apps)?

Integration Approach

Stack Fit

• Laravel Ecosystem: Seamless integration with:
  • Eloquent: Blaspable trait for model-level checks.
  • Validation: blasp_check rule or Profanity fluent object.
  • Middleware: blasp:sanitize or blasp:reject for HTTP requests.
  • Blade: @clean directive for views.
• PHP Extensions: Leverages mbstring for Unicode support and pcntl for parallel processing (if batch-checking many texts).
• Caching: Works with Laravel’s cache drivers (Redis, file, etc.) for result caching.

Migration Path

1. Pilot Phase:
   • Install in a non-production environment (e.g., staging).
   • Test with real user data to validate false positives/negatives.
   • Benchmark performance under load (e.g., using Laravel Dusk or Artisan commands).
2. Incremental Rollout:
   • Step 1: Add to validation rules for critical fields (e.g., comments, bios).
   • Step 2: Integrate middleware for API endpoints.
   • Step 3: Apply Eloquent trait to models with user-generated content.
   • Step 4: Enable Blade directives for frontend sanitization.
3. Configuration Tuning:
   • Start with lenient settings (pattern driver, mild severity) and tighten as needed.
   • Use environment-specific configs (e.g., config/blasp-local.php for dev).

Compatibility

• PHP 8.2+: Requires named arguments, enums, and attributes. No issues if using Laravel 8.0+.
• Laravel Versions: Tested on Laravel 8.0+, but check for breaking changes in newer versions (e.g., Laravel 11’s validation updates).
• Database: No schema changes required. Eloquent integration is opt-in.
• Third-Party: Conflicts unlikely, but audit for:
  • Custom Str/Stringable macros.
  • Overlapping middleware priorities.

Sequencing

1. Core Setup:
   • Publish config: php artisan vendor:publish --tag="blasp".
   • Configure default driver, language, and mask in .env.
2. Validation Layer:
   • Add blasp_check to form requests.
   • Example:

     $request->validate([
         'comment' => ['required', 'blasp_check:spanish,high'],
     ]);
     

3. Middleware:
   • Protect routes with middleware('blasp:sanitize').
   • Exclude sensitive fields in config/blasp.php:

     'middleware' => [
         'except' => ['password', 'api_token'],
     ],
     

4. Eloquent:
   • Add use Blaspsoft\Blasp\Blaspable; to models.
   • Configure blaspable attributes and blaspMode (e.g., reject for public posts).
5. Frontend:
   • Replace {{ $comment->body }} with @clean($comment->body).
6. Monitoring:
   • Set up logging for ProfanityDetected events.
   • Track blasp middleware errors in Sentry/Error Tracking.

Operational Impact

Maintenance

• Word List Updates:
  • Self-hosted: Update via composer update blaspsoft/blasp or manual config edits.
  • Cloud: Automate via API key rotation or webhook triggers.
• Driver Maintenance:
  • Custom drivers require PHP updates if leveraging new features (e.g., PHP 8.3’s str_contains).
  • Monitor for regex performance regressions in PHP upgrades.
• Configuration Drift:
  • Use Laravel’s environment configs to override settings per deployment (e.g., BLASP_DRIVER=pattern in production).

Support

• Developer Onboarding:
  • Low: Fluent API mirrors Laravel patterns. Document:
    • Common use cases (e.g., @clean, blasp_check).
    • Driver tradeoffs (e.g., "Use pattern for speed, regex for accuracy").
  • High: Custom driver development requires regex/phonetic knowledge.
• User Support:
  • False Positives: Provide a feedback mechanism (e.g., "Report False Positive" button) to populate allow() lists.