Blasp Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require blaspsoft/blasp
   php artisan vendor:publish --tag="blasp"
   

2. First Check:

   use Blaspsoft\Blasp\Facades\Blasp;
   
   $result = Blasp::check("This is a test sentence with profanity");
   if ($result->isOffensive()) {
       echo $result->clean(); // "This is a test sentence with ********"
   }
   

3. Basic Configuration: Update config/blasp.php to set default language, driver, and masking strategy.

Where to Look First

• Facade: Blaspsoft\Blasp\Facades\Blasp for fluent API usage.
• Configuration: config/blasp.php for global settings.
• Validation Rules: Blaspsoft\Blasp\Rules\Profanity for form validation.

First Use Case

Sanitize User Comments:

use Blaspsoft\Blasp\Facades\Blasp;

$comment = $request->input('comment');
$cleanedComment = Blasp::check($comment)->clean();

Implementation Patterns

Core Workflows

1. Fluent API Chaining:

   $result = Blasp::in('spanish')
       ->driver('regex')
       ->mask('#')
       ->withSeverity(Severity::High)
       ->check($text);
   

2. Eloquent Integration:

   class Comment extends Model {
       use Blaspable;
   
       protected $blaspable = ['body', 'title'];
   }
   

3. Middleware for Request Filtering:

   Route::post('/submit', SubmitController::class)
       ->middleware('blasp:sanitize,moderate');
   

Integration Tips

• Validation Rules:

  use Blaspsoft\Blasp\Rules\Profanity;
  
  $request->validate([
      'bio' => ['required', Profanity::in('english')->maxScore(30)],
  ]);
  

• Batch Processing:

  $results = Blasp::checkMany([
      "First text",
      "Second text with profanity",
  ]);
  

• Custom Drivers: Extend Blaspsoft\Blasp\Contracts\Driver for domain-specific filtering.

• Blade Directives:

  <p>@clean($user->bio)</p>
  

Common Patterns

1. Dynamic Language Selection:

   $language = $user->preferredLanguage;
   Blasp::in($language)->check($text);
   

2. Severity-Based Actions:

   $result = Blasp::withSeverity(Severity::High)->check($text);
   if ($result->severity() === Severity::High) {
       // Escalate to moderator
   }
   

3. Pipeline for Comprehensive Checks:

   Blasp::pipeline('regex', 'phonetic', 'pattern')->check($text);
   

Gotchas and Tips

Pitfalls

1. Performance with Regex Driver:

   • The regex driver is the most accurate but slowest. Use pattern for speed or pipeline with regex only when needed.
   • Cache results if checking similar content repeatedly:

     Blasp::cacheResults(true)->check($text);
     

2. False Positives in Phonetic Driver:

   • Configure false_positives in config/blasp.php to avoid flagging common words like "fork" or "duck".
   • Adjust max_distance_ratio if too many false positives/negatives occur.

3. Masking Edge Cases:

   • Custom callbacks for masking may break if not careful with HTML/JS injection. Sanitize output if displaying in HTML context.

4. Eloquent Trait Conflicts:

   • Ensure $blaspable attributes are not mass-assignable if using reject mode, or handle exceptions gracefully.

5. Middleware Field Selection:

   • Wildcard (*) in middleware.fields checks all fields. Explicitly list fields for granular control:

     'fields' => ['comment', 'title', 'bio'],
     

Debugging Tips

1. Inspect Results:

   $result = Blasp::check($text);
   dd($result->words()); // Detailed matched words with positions/severity
   

2. Test with Fake:

   Blasp::fake([
       'fuck' => ['severity' => Severity::High],
   ]);
   

3. Log Detected Profanity:

   Blasp::check($text)->words()->each(function ($word) {
       Log::warning("Profanity detected: {$word->word} (severity: {$word->severity})");
   });
   

Configuration Quirks

1. Language-Specific Settings:

   • Some drivers (e.g., phonetic) only support specific languages. Check drivers.phonetic.supported_languages.

2. Cache Behavior:

   • Enable cache.results to cache check results by content hash, but disable if content is highly dynamic.

3. Severity Enums:

   • Ensure your Severity enum matches the package's (Blaspsoft\Blasp\Enums\Severity).

Extension Points

1. Custom Drivers:

   class MyCustomDriver implements Driver {
       public function check(string $text): Result {
           // Implement custom logic
       }
   }
   

   Register in config/blasp.php:

   'drivers' => [
       'my_custom' => MyCustomDriver::class,
   ],
   

2. Override Default Masking:

   Blasp::mask(fn($word, $len) => str_repeat('X', $len))->check($text);
   

3. Extend Validation Rules:

   use Blaspsoft\Blasp\Rules\Profanity as BaseProfanity;
   
   class CustomProfanity extends BaseProfanity {
       public function passes($attribute, $value) {
           // Custom logic
       }
   }
   

4. Listen to Events:

   Event::listen(ProfanityDetected::class, function ($event) {
       // Handle detected profanity
   });
   

Performance Tips

• Disable Events in Production:

  'events' => env('APP_ENV') !== 'production',
  

• Use pattern Driver for Bulk Checks:

  Blasp::driver('pattern')->checkMany($largeArrayOfTexts);
  

• Batch Eloquent Saves: Use withoutBlaspChecking for bulk operations where performance is critical.