feat: add non-English severity maps and result caching

Add severity maps (mild/moderate/extreme) for Spanish, French, and German
so withSeverity() filtering works correctly for all languages instead of
defaulting everything to High.

Implement result caching in PendingCheck — check() results are cached by
a hash of all parameters (text, driver, language, severity, allow/block
lists, mask strategy). CallbackMask bypasses cache since closures can't
serialize. Add Result::fromArray() for deserialization, extend
Dictionary::clearCache() to also clear result cache, and add
cache.results config toggle.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: deemonic

README.md

@@ -17,7 +17,7 @@ Blasp is a powerful, extensible profanity filter for Laravel. Version 4 is a gro
 
 ## Features
 
-- **Driver Architecture** — `regex` (detects obfuscation, substitutions, separators), `pattern` (fast exact matching), or `phonetic` (catches sound-alike evasions). Extend with custom drivers.
+- **Driver Architecture** — `regex` (detects obfuscation, substitutions, separators), `pattern` (fast exact matching), `phonetic` (catches sound-alike evasions), or `pipeline` (chains multiple drivers together). Extend with custom drivers.
 - **Multi-Language** — English, Spanish, German, French with language-specific normalizers. Check one, many, or all at once.
 - **Severity Scoring** — Words categorised as mild/moderate/high/extreme. Filter by minimum severity and get a 0-100 score.
 - **Masking Strategies** — Character mask (`*`, `#`), grawlix (`!@#$%`), or a custom callback.
@@ -87,6 +87,11 @@ Blasp::french()->check($text);
 Blasp::driver('regex')->check($text);     // Full obfuscation detection (default)
 Blasp::driver('pattern')->check($text);   // Fast exact matching
 Blasp::driver('phonetic')->check($text);  // Sound-alike detection (e.g. "phuck", "sheit")
+Blasp::driver('pipeline')->check($text);  // Chain multiple drivers (config-based)
+
+// Ad-hoc pipeline — chain any drivers without config
+Blasp::pipeline('regex', 'phonetic')->check($text);
+Blasp::pipeline('pattern', 'phonetic')->in('english')->mask('#')->check($text);
 
 // Shorthand modes
 Blasp::strict()->check($text);   // Forces regex driver
@@ -160,6 +165,31 @@ The phonetic driver uses `metaphone()` + Levenshtein distance to catch words tha
 
 Configure sensitivity in `config/blasp.php` under `drivers.phonetic`. A curated false-positive list prevents common words like "fork", "duck", and "beach" from being flagged.
 
+### Pipeline Driver
+
+The pipeline driver chains multiple drivers together so a single `check()` call runs all of them. It uses **union merge** semantics — text is flagged if **any** driver finds a match.
+
+```php
+// Config-based: set 'default' => 'pipeline' or use driver('pipeline')
+Blasp::driver('pipeline')->check('phuck this sh1t');
+
+// Ad-hoc: pick drivers on the fly (no config needed)
+Blasp::pipeline('regex', 'phonetic')->check('phuck this sh1t');
+Blasp::pipeline('regex', 'pattern', 'phonetic')->check($text);
+```
+
+When multiple drivers detect the same word at the same position, duplicates are removed — only the longest match is kept. Masks are applied from the merged result, and the score is recalculated across all matches.
+
+Configure the default sub-drivers in `config/blasp.php`:
+
+```php
+'drivers' => [
+    'pipeline' => [
+        'drivers' => ['regex', 'phonetic'],  // Drivers to chain
+    ],
+],
+```
+
 ## Eloquent Integration
 
 The `Blaspable` trait automatically checks model attributes during save:
@@ -335,7 +365,7 @@ Full `config/blasp.php` reference:
 
 ```php
 return [
-    'default'   => env('BLASP_DRIVER', 'regex'),       // 'regex' | 'pattern' | 'phonetic'
+    'default'   => env('BLASP_DRIVER', 'regex'),       // 'regex' | 'pattern' | 'phonetic' | 'pipeline'
     'language'  => env('BLASP_LANGUAGE', 'english'),    // Default language
     'mask'      => '*',                                 // Default mask character
     'severity'  => 'mild',                              // Minimum severity
@@ -345,6 +375,7 @@ return [
         'enabled' => true,
         'driver'  => env('BLASP_CACHE_DRIVER'),
         'ttl'     => 86400,
+        'results' => true,          // Cache check() results by content hash
     ],
 
     'middleware' => [
@@ -359,6 +390,9 @@ return [
     ],
 
     'drivers' => [
+        'pipeline' => [
+            'drivers' => ['regex', 'phonetic'],    // Sub-drivers to chain
+        ],
         'phonetic' => [
             'phonemes' => 4,                       // metaphone code length (2-8)
             'min_word_length' => 3,                // skip short words
@@ -402,6 +436,41 @@ Blasp::extend('my-driver', fn($app) => new MyDriver());
 Blasp::driver('my-driver')->check($text);
 ```
 
+## Caching
+
+Blasp caches `check()` results by default. When the same text is checked with the same configuration (language, driver, severity, allow/block lists), the cached result is returned instantly.
+
+```php
+// First call — runs full analysis, caches result
+$result = Blasp::check('some text');
+
+// Second call — returns cached result
+$result = Blasp::check('some text');
+```
+
+Configure caching in `config/blasp.php`:
+
+```php
+'cache' => [
+    'enabled' => true,                      // Master switch for all caching
+    'driver'  => env('BLASP_CACHE_DRIVER'), // null = default cache driver
+    'ttl'     => 86400,                     // Cache lifetime in seconds
+    'results' => true,                      // Cache check() results (disable independently)
+],
+```
+
+Result caching is automatically bypassed when using a `CallbackMask` (closures can't be serialized). Clear both dictionary and result caches with:
+
+```bash
+php artisan blasp:clear
+```
+
+Or programmatically:
+
+```php
+Dictionary::clearCache();
+```
+
 ## Artisan Commands
 
 ```bash

config/blasp.php

@@ -70,6 +70,7 @@
         'enabled' => true,
         'driver' => env('BLASP_CACHE_DRIVER'),
         'ttl' => 86400,
+        'results' => true,
     ],
 
     // Backward compat alias

config/languages/french.php

@@ -1,6 +1,41 @@
 <?php
 
 return [
+    'severity' => [
+        'mild' => [
+            'crotte', 'crottes', 'caca', 'cacas', 'zut',
+            'mince', 'flûte', 'flute', 'punaise',
+            'idiot', 'idiots', 'idiote', 'idiotes',
+            'bête', 'bete', 'bêtes', 'betes',
+            'sot', 'sots', 'sotte', 'sottes',
+            'niais', 'niaise', 'niaises',
+            'ballot', 'ballots', 'andouille', 'andouilles',
+        ],
+        'moderate' => [
+            'connard', 'connarde', 'con', 'conne',
+            'salaud', 'salope', 'garce', 'garces',
+            'pétasse', 'petasse', 'pétasses', 'petasses',
+            'bâtard', 'batard', 'bâtards', 'batards',
+            'bâtarde', 'batarde', 'bâtardes', 'batardes',
+            'abruti', 'abrutis', 'abrutie', 'abruties',
+            'crétin', 'cretin', 'crétins', 'cretins',
+            'crétine', 'cretine', 'crétines', 'cretines',
+            'débile', 'debile', 'débiles', 'debiles',
+            'imbécile', 'imbecile', 'imbéciles', 'imbeciles',
+            'cul', 'culs', 'trou du cul', 'trou de balle',
+            'cochon', 'cochons', 'cochonne', 'cochonnes',
+        ],
+        'extreme' => [
+            'pédé', 'pede', 'pédés', 'pedes',
+            'pédéraste', 'pederaste', 'pédérastes', 'pederastes',
+            'tapette', 'tapettes', 'tantouze', 'tantouzes',
+            'fiotte', 'fiottes', 'tarlouze', 'tarlouzes',
+            'gouine', 'gouines',
+            'attardé', 'attarde', 'attardés', 'attardes',
+            'attardée', 'attardee', 'attardées', 'attardees',
+        ],
+    ],
+
     'profanities' => [
         // Common French profanities and vulgar expressions
         'merde',

config/languages/german.php

@@ -1,6 +1,36 @@
 <?php
 
 return [
+    'severity' => [
+        'mild' => [
+            'mist', 'kacke', 'verdammt', 'verdammte', 'verdammter', 'verdammtes',
+            'blöd', 'bloed', 'blöde', 'bloede', 'blöder', 'bloeder', 'blödes', 'bloedes',
+            'doof', 'doofe', 'doofer', 'doofes',
+            'dumm', 'dumme', 'dummer', 'dummes',
+            'albern', 'alberne', 'alberner', 'albernes',
+            'peinlich', 'peinliche', 'peinlicher', 'peinliches',
+        ],
+        'moderate' => [
+            'arsch', 'arschloch', 'arschlöcher', 'arschlocher',
+            'schlampe', 'nutte', 'hure',
+            'wichser', 'depp', 'trottel',
+            'idiot', 'vollidiot',
+            'bescheuert', 'bescheuerte', 'bescheuerter', 'bescheuertes',
+            'bekloppt', 'bekloppte', 'bekloppter', 'beklopptes',
+            'schwanz', 'pimmel',
+            'hintern', 'po', 'popo',
+        ],
+        'extreme' => [
+            'schwul', 'schwuler', 'schwule', 'schwules',
+            'tunte', 'tuntig',
+            'kampflesbe', 'kampflesben',
+            'kanake', 'kanaken',
+            'neger', 'negerin',
+            'zigeuner', 'zigeunerin',
+            'retardiert', 'retardierte', 'retardierter',
+        ],
+    ],
+
     'profanities' => [
         // Common German profanities and vulgar expressions
         'scheiße',

config/languages/spanish.php

@@ -1,6 +1,31 @@
 <?php
 
 return [
+    'severity' => [
+        'mild' => [
+            'maldito', 'maldita', 'maldición', 'maldicion', 'carajo',
+            'hostia', 'hostias', 'jolines', 'joline', 'jobar', 'joroba',
+            'caca', 'mear', 'meada', 'peo', 'pedorro', 'pedorra', 'pedos',
+            'tonto', 'tonta', 'bobo', 'boba', 'baboso', 'babosa',
+            'cursi', 'pesado', 'pesada', 'latoso', 'latosa',
+        ],
+        'moderate' => [
+            'cabrón', 'cabron', 'cabrona', 'cabrones', 'cabronazo',
+            'perra', 'zorra', 'gilipollas', 'gilipolla',
+            'imbécil', 'imbecil', 'idiota', 'estúpido', 'estupido', 'estúpida', 'estupida',
+            'pendejo', 'pendeja', 'mamón', 'mamon',
+            'boludo', 'boluda', 'pelotudo', 'pelotuda',
+            'culo', 'ojete', 'putilla', 'putita',
+            'capullo', 'coñazo', 'conazo', 'putada',
+        ],
+        'extreme' => [
+            'maricón', 'maricon', 'marica', 'maricona', 'mariconazo',
+            'tortillera', 'bollera',
+            'retrasado', 'retrasada', 'retardado', 'retardada',
+            'mongoloide', 'subnormal',
+        ],
+    ],
+
     'profanities' => [
         // Common Spanish profanities and vulgar expressions
         'mierda',

src/Core/Dictionary.php

@@ -325,6 +325,15 @@ public static function clearCache(): void
         }
 
         $cache->forget('blasp_cache_keys');
+
+        // Also clear result cache keys
+        $resultKeys = $cache->get('blasp_result_cache_keys', []);
+
+        foreach ($resultKeys as $key) {
+            $cache->forget($key);
+        }
+
+        $cache->forget('blasp_result_cache_keys');
     }
 
     private static function getCache(): \Illuminate\Contracts\Cache\Repository

src/Core/Result.php

@@ -114,6 +114,28 @@ public static function none(string $text): self
         return new self($text, $text, [], 0);
     }
 
+    public static function fromArray(array $data): self
+    {
+        $matchedWords = [];
+        foreach ($data['words'] ?? [] as $wordData) {
+            $matchedWords[] = new MatchedWord(
+                text: $wordData['text'],
+                base: $wordData['base'],
+                severity: Severity::tryFrom($wordData['severity']) ?? Severity::High,
+                position: $wordData['position'],
+                length: $wordData['length'],
+                language: $wordData['language'] ?? 'english',
+            );
+        }
+
+        return new self(
+            $data['original'] ?? '',
+            $data['clean'] ?? '',
+            $matchedWords,
+            $data['score'] ?? 0,
+        );
+    }
+
     public static function withMatches(array $words, string $originalText = '', string $cleanText = ''): self
     {
         $matchedWords = [];

src/PendingCheck.php

@@ -13,6 +13,7 @@
 use Blaspsoft\Blasp\Drivers\PipelineDriver;
 use Blaspsoft\Blasp\Enums\Severity;
 use Blaspsoft\Blasp\Events\ProfanityDetected;
+use Illuminate\Support\Facades\Cache;
 
 class PendingCheck
 {
@@ -161,6 +162,29 @@ public function check(?string $text): Result
     {
         $text = $text ?? '';
 
+        if ($this->shouldCache()) {
+            $cacheKey = $this->buildCacheKey($text);
+            $cache = $this->getCache();
+            $ttl = config('blasp.cache.ttl', 86400);
+
+            $cached = $cache->get($cacheKey);
+            if ($cached !== null) {
+                return Result::fromArray($cached);
+            }
+
+            $result = $this->performCheck($text);
+
+            $cache->put($cacheKey, $result->toArray(), $ttl);
+            $this->trackCacheKey($cacheKey);
+
+            return $result;
+        }
+
+        return $this->performCheck($text);
+    }
+
+    protected function performCheck(string $text): Result
+    {
         $dictionary = $this->buildDictionary();
         $driver = $this->resolveDriver();
         $mask = $this->resolveMask();
@@ -243,4 +267,57 @@ protected function resolveMask(): MaskStrategyInterface
         $maskConfig = config('blasp.mask', config('blasp.mask_character', '*'));
         return new CharacterMask($maskConfig);
     }
+
+    // --- Caching ---
+
+    protected function shouldCache(): bool
+    {
+        if (!config('blasp.cache.enabled', true)) {
+            return false;
+        }
+
+        if (!config('blasp.cache.results', true)) {
+            return false;
+        }
+
+        if ($this->maskStrategy instanceof CallbackMask) {
+            return false;
+        }
+
+        return true;
+    }
+
+    protected function buildCacheKey(string $text): string
+    {
+        $parts = [
+            'text' => $text,
+            'driver' => $this->driverName ?? config('blasp.default', 'regex'),
+            'pipeline' => $this->pipelineDrivers,
+            'languages' => $this->languages,
+            'all_languages' => $this->allLanguages,
+            'allow' => $this->allowList,
+            'block' => $this->blockList,
+            'severity' => $this->minimumSeverity?->value,
+            'strict' => $this->strictMode,
+            'lenient' => $this->lenientMode,
+            'mask' => $this->maskStrategy ? serialize($this->maskStrategy) : null,
+        ];
+
+        return 'blasp_result_' . md5(serialize($parts));
+    }
+
+    protected function getCache(): \Illuminate\Contracts\Cache\Repository
+    {
+        $driver = config('blasp.cache.driver', config('blasp.cache_driver'));
+
+        return $driver !== null ? Cache::store($driver) : Cache::store();
+    }
+
+    protected function trackCacheKey(string $key): void
+    {
+        $cache = $this->getCache();
+        $keys = $cache->get('blasp_result_cache_keys', []);
+        $keys[] = $key;
+        $cache->forever('blasp_result_cache_keys', array_unique($keys));
+    }
 }