README

Blasp - Advanced Profanity Filter for Laravel

Blasp is a powerful, extensible profanity filter package for Laravel that helps detect and mask profane words in text. Version 3.0 introduces a simplified API with method chaining, comprehensive multi-language support (English, Spanish, German, French), all-languages detection mode, and advanced caching for enterprise-grade performance.

✨ Key Features

🔗 Method Chaining: Elegant fluent API with Blasp::spanish()->check()
🌍 Multi-Language Support: English, Spanish, German, and French with language-specific normalizers
🌐 All Languages Mode: Check against all languages simultaneously with Blasp::allLanguages()
🎨 Custom Masking: Configure custom mask characters with maskWith() method
⚡ High Performance: Advanced caching with O(1) lookups and optimized algorithms
🎯 Smart Detection: Handles substitutions, separators, variations, and false positives
🏗️ Modern Architecture: Built on SOLID principles with dependency injection
✅ Battle Tested: 148 tests with 858 assertions ensuring reliability

Installation

You can install the package via Composer:

composer require blaspsoft/blasp

Quick Start

Basic Usage

use Blaspsoft\Blasp\Facades\Blasp;

// Simple usage - uses default language from config
$result = Blasp::check('This is a fucking shit sentence');

// With method chaining for specific language
$result = Blasp::spanish()->check('esto es una mierda');

// Check against ALL languages at once
$result = Blasp::allLanguages()->check('fuck merde scheiße mierda');

Simplified API with Method Chaining

// Language shortcuts
Blasp::english()->check($text);
Blasp::spanish()->check($text);
Blasp::german()->check($text);
Blasp::french()->check($text);

// Check against all languages
Blasp::allLanguages()->check($text);

// Custom mask character
Blasp::maskWith('#')->check($text);
Blasp::maskWith('●')->check($text);

// Configure custom profanities
Blasp::configure(['badword'], ['goodword'])->check($text);

// Chain multiple methods together
Blasp::spanish()->maskWith('*')->check($text);
Blasp::allLanguages()->maskWith('-')->check($text);

Working with Results

$result = Blasp::check('This is fucking awesome');

$result->getSourceString();           // "This is fucking awesome"
$result->getCleanString();            // "This is ******* awesome"
$result->hasProfanity();             // true
$result->getProfanitiesCount();      // 1
$result->getUniqueProfanitiesFound(); // ['fucking']

// With custom mask character
$result = Blasp::maskWith('#')->check('This is fucking awesome');
$result->getCleanString();            // "This is ####### awesome"

Profanity Detection Types

Blasp can detect different types of profanities based on variations such as:

Straight match: Direct matches of profane words.
Substitution: Substituted characters (e.g., pro0fán1ty).
Obscured: Profanities with separators (e.g., p-r-o-f-a-n-i-t-y).
Doubled: Repeated letters (e.g., pprrooffaanniittyy).
Combination: Combinations of the above (e.g., pp-rof@n|tty).

Laravel Validation Rule

Blasp also provides a custom Laravel validation rule called blasp_check, which you can use to validate form input for profanity.

Example

$request->merge(['sentence' => 'This is f u c k 1 n g awesome!']);

$validated = $request->validate([
    'sentence' => ['blasp_check'],
]);

// With language specification
$validated = $request->validate([
    'sentence' => ['blasp_check:spanish'],
]);

Configuration

Blasp uses configuration files to manage profanities, separators, and substitutions. The main configuration includes:

// config/blasp.php
return [
    'default_language' => 'english',  // Default language for detection
    'mask_character' => '*',          // Default character for masking profanities
    'separators' => [...],            // Special characters used as separators
    'substitutions' => [...],         // Character substitutions (like @ for a)
    'false_positives' => [...],       // Words that should not be flagged
];

You can publish the configuration files:

# Publish everything (config + all language files)
php artisan vendor:publish --tag="blasp"

# Publish only the main configuration file
php artisan vendor:publish --tag="blasp-config"

# Publish only the language files
php artisan vendor:publish --tag="blasp-languages"

This will publish:

config/blasp.php - Main configuration with default language settings
config/languages/ - Language-specific profanity lists (English, Spanish, German, French)

Custom Configuration

You can specify custom profanity and false positive lists using the configure() method:

use Blaspsoft\Blasp\Facades\Blasp;

$blasp = Blasp::configure(
    profanities: $your_custom_profanities,
    falsePositives: $your_custom_false_positives
)->check($text);

This is particularly useful when you need different profanity rules for specific contexts, such as username validation.

🚀 Advanced Features (v3.0+)

All Languages Detection

Perfect for international platforms, forums, or any application with multilingual content:

// Check text against ALL configured languages at once
$result = Blasp::allLanguages()->check('fuck merde scheiße mierda');
// Detects profanities from English, French, German, and Spanish

// Get detailed results
echo $result->getProfanitiesCount();        // 4
echo $result->getUniqueProfanitiesFound();  // ['fuck', 'merde', 'scheiße', 'mierda']

Multi-Language Support

Blasp includes comprehensive support for multiple languages with automatic character normalization:

English: Full profanity database with common variations
Spanish: Handles accent normalization (á→a, ñ→n)
German: Processes umlauts (ä→ae, ö→oe, ü→ue) and ß→ss
French: Accent and cedilla normalization

Complete Chainable Methods Reference

// Language selection methods
Blasp::language('spanish')     // Set any language by name
Blasp::english()               // Shortcut for English
Blasp::spanish()               // Shortcut for Spanish
Blasp::german()                // Shortcut for German
Blasp::french()                // Shortcut for French
Blasp::allLanguages()          // Check against all languages

// Configuration methods
Blasp::configure($profanities, $falsePositives)  // Custom word lists
Blasp::maskWith('#')                             // Custom mask character

// Detection method
Blasp::check($text)            // Analyze text for profanities

// All methods return BlaspService for chaining
$service = Blasp::spanish()                      // Returns BlaspService
    ->maskWith('●')                              // Returns BlaspService
    ->configure(['custom'], ['false_positive'])  // Returns BlaspService
    ->check('texto para verificar');             // Returns BlaspService with results

Advanced Method Chaining Examples

// Example 1: Spanish with custom mask
Blasp::spanish()
    ->maskWith('#')
    ->check('esto es una mierda');
// Result: "esto es una ######"

// Example 2: All languages with custom configuration
Blasp::allLanguages()
    ->configure(['newbadword'], ['safephrase'])
    ->maskWith('-')
    ->check('multiple fuck merde languages');
// Result: "multiple ---- ----- languages"

// Example 3: Dynamic language selection
$language = $user->preferred_language; // 'french'
Blasp::language($language)
    ->maskWith($user->mask_preference ?? '*')
    ->check($userContent);

Laravel Integration

// Laravel service container integration
$blasp = app(BlaspService::class);

// Validation rule with default language
$request->validate([
    'message' => 'required|blasp_check'
]);

// Validation rule with specific language
$request->validate([
    'message' => 'required|blasp_check:spanish'
]);

Cache Management

Blasp uses Laravel's cache system to improve performance. The package automatically caches profanity expressions and their variations. To clear the cache, you can use the provided Artisan command:

php artisan blasp:clear

This command will clear all cached Blasp expressions and configurations.

⚡ Performance

Blasp v3.0 includes significant performance optimizations:

Cached Expression Sorting: Profanity expressions are sorted once and cached, eliminating repeated O(n log n) operations
Hash Map Lookups: False positive checking and unique profanity tracking use O(1) hash map lookups instead of O(n) linear searches
Optimized Regular Expressions: Improved regex generation and matching algorithms
Intelligent Caching: Multi-layer caching system with automatic cache invalidation

Benchmarks

Version 3.0 shows substantial performance improvements over v2:

Expression Processing: 60% faster profanity expression generation
Detection Speed: 40% faster text analysis with large profanity lists
Memory Usage: 30% reduction in memory footprint
Cache Efficiency: 80% fewer database/config queries with intelligent caching

🔄 Migration from v2.x to v3.0

100% Backward Compatible

All existing v2.x code continues to work without any changes:

// Existing code works exactly the same
use Blaspsoft\Blasp\Facades\Blasp;

$result = Blasp::check('text to check');
$result = Blasp::configure($profanities, $falsePositives)->check('text');

New Features in v3.0

Take advantage of the simplified API:

// NEW: Method chaining
Blasp::spanish()->check($text);

// NEW: All languages detection
Blasp::allLanguages()->check($text);

// NEW: Language shortcuts
Blasp::german()->check($text);
Blasp::french()->check($text);

// NEW: Custom mask characters
Blasp::maskWith('#')->check($text);
Blasp::spanish()->maskWith('●')->check($text);

// NEW: Default language configuration
// Set in config/blasp.php: 'default_language' => 'spanish'
Blasp::check($text); // Now uses Spanish by default

🎨 Custom Masking

Using Custom Mask Characters

You can customize how profanities are masked using the maskWith() method:

// Use hash symbols instead of asterisks
$result = Blasp::maskWith('#')->check('This is fucking awesome');
echo $result->getCleanString(); // "This is ####### awesome"

// Use dots for masking
$result = Blasp::maskWith('·')->check('What the hell');
echo $result->getCleanString(); // "What the ····"

// Unicode characters work too
$result = Blasp::maskWith('●')->check('damn it');
echo $result->getCleanString(); // "●●●● it"

Setting Default Mask Character

You can set a default mask character in the configuration:

// config/blasp.php
return [
    'mask_character' => '#',  // All profanities will be masked with #
    // ...
];

Combining with Other Methods

The maskWith() method can be chained with other methods:

// Spanish text with custom mask
Blasp::spanish()->maskWith('@')->check('esto es mierda');

// All languages with dots
Blasp::allLanguages()->maskWith('·')->check('multilingual text');

// Configure and mask
Blasp::configure(['custom'], [])
    ->maskWith('-')
    ->check('custom text');

🏗️ Architecture

Blasp v3.0 follows SOLID principles and modern PHP practices:

Facade Pattern: Simplified API with Laravel facade integration
Builder Pattern: Method chaining for fluent interface
Strategy Pattern: Language-specific detection and normalization
Dependency Injection: Full Laravel service container integration
Caching: Intelligent performance optimization

📋 Requirements

PHP 8.1+
Laravel 10.0+
BCMath PHP Extension (for advanced calculations)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 Changelog

See CHANGELOG.md for detailed version history.

License

Blasp is open-sourced software licensed under the MIT license.

blaspsoft / blasp

Maintainers

Details