Blasp

https://github.com/blaspsoft/blasp
Admin
Blasp is an advanced, extensible profanity filter package for Laravel that detects and masks profane...
Tokens:33,680
Snippets:211
Trust Score:5.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Blasp with Composer

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Installs the Blasp package via Composer. Requires PHP 8.2+ and Laravel 8.0+.

```bash
composer require blaspsoft/blasp
```

--------------------------------

### Quick Start: Check Profanity with Blasp Facade

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Performs a basic profanity check using the Blasp facade. The returned result object provides methods to check if offensive, get the cleaned text, original text, score, count, unique words, and severity.

```php
use Blaspsoft\Blasp\Facades\Blasp;

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

$result->isOffensive();  // true
$result->clean();         // "This is a ******* sentence"
$result->original();      // "This is a fucking sentence"
$result->score();         // 30
$result->count();         // 1
$result->uniqueWords();   // ['fucking']
$result->severity();      // Severity::High
```

--------------------------------

### Sanitize mode example

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

In sanitize mode (default), profanity is masked and the model saves. Use hadProfanity(), blaspResults(), and blaspResult() to inspect results.

```php
// Sanitize mode (default) — profanity is masked, model saves
$comment = Comment::create(['body' => 'This is fucking great']);
$comment->body; // "This is ******* great"

// Check what happened
$comment->hadProfanity();            // true
$comment->blaspResults();            // ['body' => Result, 'title' => Result]
$comment->blaspResult('body');       // Result instance
```

--------------------------------

### Validate strings with blasp_check rule

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Example of using the 'blasp_check' validation rule with optional language parameter. The rule checks the field for profanity.

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

--------------------------------

### Using the pipeline driver with Blasp::driver and Blasp::pipeline

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shows how to use the pipeline driver. The first line uses the config-based approach with the 'pipeline' driver, while the next two lines show ad-hoc pipeline creation with selected drivers. The pipeline uses union merge semantics: text is flagged if any driver finds a match.

```php
Blasp::driver('pipeline')->check('phuck this sh1t');
```

```php
Blasp::pipeline('regex', 'phonetic')->check('phuck this sh1t');
```

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

--------------------------------

### Implement and register a custom driver

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shows how to implement DriverInterface with a detect() method and register the driver via Blasp::extend(). Use Blasp::driver('my-driver')->check($text) to invoke it.

```php
use Blaspsoft\Blasp\Core\Contracts\DriverInterface;
use Blaspsoft\Blasp\Core\Result;
use Blaspsoft\Blasp\Core\Dictionary;
use Blaspsoft\Blasp\Core\Contracts\MaskStrategyInterface;

class MyDriver implements DriverInterface
{
    public function detect(string $text, Dictionary $dictionary, MaskStrategyInterface $mask, array $options = []): Result
    {
        // Your detection logic
    }
}

// Register in a service provider
Blasp::extend('my-driver', fn($app) => new MyDriver());

// Use it
Blasp::driver('my-driver')->check($text);
```

--------------------------------

### POST /pipeline

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Creates an ad-hoc pipeline of drivers for the check.

```APIDOC
## [POST] /pipeline

### Description
Creates an ad-hoc pipeline of drivers for the check.

### Method
POST

### Endpoint
/pipeline

### Parameters
#### Request Body
- **drivers** (array of strings) - Required - List of driver names to chain.
- **text** (string) - Required - The text to check.

### Request Example
{
  "drivers": ["regex", "phonetic"],
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### Fluent API: Language, Driver, Masking, and More

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shows the fluent API for configuring language, driver, masking, severity, allow/block lists, and batch checking. All builder methods return a PendingCheck and can be chained.

```php
// Language selection
Blasp::in('spanish')->check($text);
Blasp::in('english', 'french')->check($text);
Blasp::inAllLanguages()->check($text);

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

// Driver selection
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
Blasp::lenient()->check($text);  // Forces pattern driver

// Masking
Blasp::mask('*')->check($text);        // Character mask (default)
Blasp::mask('#')->check($text);        // Custom character
Blasp::mask('grawlix')->check($text);  // !@#$% cycling
Blasp::mask(fn($word, $len) => '[CENSORED]')->check($text);  // Callback

// Severity filtering
use Blaspsoft\Blasp\Enums\Severity;
Blasp::withSeverity(Severity::High)->check($text);  // Ignores mild/moderate

// Allow/block lists (merged with config)
Blasp::allow('damn', 'hell')->check($text);
Blasp::block('customword')->check($text);

// Chain everything
Blasp::spanish()
    ->mask('#')
    ->withSeverity(Severity::Moderate)
    ->check($text);

// Batch checking
$results = Blasp::checkMany(['text one', 'text two']);
```

--------------------------------

### Publish Blasp Configuration and Language Files

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Publishes the package configuration and language files. Use the 'blasp' tag for everything, 'blasp-config' for config only, and 'blasp-languages' for language files only.

```bash
# Everything (config + language files)
php artisan vendor:publish --tag="blasp"

# Config only
php artisan vendor:publish --tag="blasp-config"

# Language files only
php artisan vendor:publish --tag="blasp-languages"
```

--------------------------------

### Blasp::driver('pipeline')->check()

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Documentation for using the pipeline driver via the Blasp facade's driver method.

```APIDOC
## Blasp::driver('pipeline')->check()

### Description
Runs the pipeline driver with the configured sub-drivers to check text for profanity. The pipeline driver chains multiple drivers together and uses union merge semantics — text is flagged if any driver finds a match.

### Method
`check()`

### Parameters
- **text** (string) - Required - The text to check for profanity.

### Example
```php
Blasp::driver('pipeline')->check('phuck this sh1t');
```
```

--------------------------------

### Configure caching in config/blasp.php

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shows the cache configuration array with options for enabling caching, setting the driver, TTL, and whether to cache check() results. The 'results' option can be disabled independently.

```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)
],
```

--------------------------------

### Blasp::pipeline('regex', 'phonetic')->check()

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Documentation for creating an ad-hoc pipeline driver with the Blasp facade's pipeline method.

```APIDOC
## Blasp::pipeline('regex', 'phonetic')->check()

### Description
Creates an ad-hoc pipeline driver with the specified sub-drivers and checks the given text for profanity. This allows picking drivers on the fly without configuration.

### Method
`pipeline()` then `check()`

### Parameters
- **drivers** (string...) - Required - One or more driver names to chain (e.g., 'regex', 'phonetic', 'pattern').
- **text** (string) - Required - The text to check for profanity.

### Example
```php
Blasp::pipeline('regex', 'phonetic')->check('phuck this sh1t');
Blasp::pipeline('regex', 'pattern', 'phonetic')->check($text);
```
```

--------------------------------

### Configure middleware fields in config/blasp.php

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Configuration array for the middleware, specifying the action (reject or sanitize), fields to check, exceptions, and severity. The default action is 'reject' which returns 422 JSON with field errors.

```php
'middleware' => [
    'action' => 'reject',
    'fields' => ['*'],                            // '*' = all fields
    'except' => ['password', 'email', '_token'],  // Always skipped
    'severity' => 'mild',
],
```

--------------------------------

### Register CheckProfanity middleware with alias and parameters

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shows three ways to apply the 'blasp' middleware: using the short alias, with parameters for action and severity, or using the class directly. The alias is registered automatically.

```php
// Using the short alias (recommended)
Route::post('/comment', CommentController::class)
    ->middleware('blasp');

// With parameters: action, severity
Route::post('/comment', CommentController::class)
    ->middleware('blasp:sanitize,mild');

// Or using the class directly
use Blaspsoft\Blasp\Middleware\CheckProfanity;

Route::post('/comment', CommentController::class)
    ->middleware(CheckProfanity::class);
```

--------------------------------

### POST /driver

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Selects the detection driver to use for the check.

```APIDOC
## [POST] /driver

### Description
Selects the detection driver to use for the check.

### Method
POST

### Endpoint
/driver

### Parameters
#### Request Body
- **driver** (string) - Required - The driver name: 'regex', 'pattern', 'phonetic', or 'pipeline'.
- **text** (string) - Required - The text to check.

### Request Example
{
  "driver": "regex",
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /in

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Sets the language(s) for the check. Can be chained with other builder methods.

```APIDOC
## [POST] /in

### Description
Sets the language(s) for the check. Can be chained with other builder methods.

### Method
POST

### Endpoint
/in

### Parameters
#### Request Body
- **languages** (array of strings) - Required - List of language codes (e.g., 'english', 'spanish').
- **text** (string) - Required - The text to check.

### Request Example
{
  "languages": ["spanish"],
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### Configure Blasp via config/blasp.php

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Full config/blasp.php reference. Configure the default driver, language, mask, severity, event firing, caching, middleware behavior, model mode, and driver-specific options. The phonetic driver has constraints: phonemes 2-8, max_distance_ratio 0.3-0.8, and metaphone is English-oriented.

```php
return [
    'default'   => env('BLASP_DRIVER', 'regex'),       // 'regex' | 'pattern' | 'phonetic' | 'pipeline'
    'language'  => env('BLASP_LANGUAGE', 'english'),    // Default language
    'mask'      => '*',                                 // Default mask character
    'severity'  => 'mild',                              // Minimum severity
    'events'    => false,                               // Fire ProfanityDetected events

    'cache' => [
        'enabled' => true,
        'driver'  => env('BLASP_CACHE_DRIVER'),
        'ttl'     => 86400,
        'results' => true,          // Cache check() results by content hash
    ],

    'middleware' => [
        'action'   => 'reject',
        'fields'   => ['*'],
        'except'   => ['password', 'email', '_token'],
        'severity' => 'mild',
    ],

    'model' => [
        'mode' => env('BLASP_MODEL_MODE', 'sanitize'),  // 'sanitize' | 'reject'
    ],

    'drivers' => [
        'pipeline' => [
            'drivers' => ['regex', 'phonetic'],    // Sub-drivers to chain
        ],
        'phonetic' => [
            'phonemes' => 4,                       // metaphone code length (2-8)
            'min_word_length' => 3,                // skip short words
            'max_distance_ratio' => 0.6,           // levenshtein threshold (0.3-0.8)
            'supported_languages' => ['english'],  // metaphone is English-oriented
            'false_positives' => ['fork', '...'],  // never flag these words
        ],
    ],

    'allow'  => [],    // Global allow-list
    'block'  => [],    // Global block-list

    'separators'      => [...],  // Characters treated as separators
    'substitutions'   => [...],  // Character leet-speak mappings
    'false_positives' => [...],  // Words that should never be flagged
];
```

--------------------------------

### Configure pipeline sub-drivers in config/blasp.php

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Configuration snippet for the pipeline driver in config/blasp.php. Sets the default sub-drivers to chain, here 'regex' and 'phonetic'.

```php
'drivers' => [
    'pipeline' => [
        'drivers' => ['regex', 'phonetic'],  // Drivers to chain
    ],
],
```

--------------------------------

### Run Blasp Artisan Commands

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Artisan commands for clearing the profanity cache, testing text from the command line, and listing available languages with word counts.

```bash
php artisan blasp:clear
```

```bash
php artisan blasp:test "some text to check" --lang=english --detail
```

```bash
php artisan blasp:languages
```

--------------------------------

### Fake Blasp Facade for Testing

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Use Blasp::fake() to replace the facade with a fake that returns clean results by default, or pre-configure specific responses. Includes assertions like assertChecked(), assertCheckedTimes(), and assertCheckedWith().

```php
use Blaspsoft\Blasp\Facades\Blasp;
use Blaspsoft\Blasp\Core\Result;

// Replace with a fake — all checks return clean by default
Blasp::fake();

// Pre-configure specific responses
Blasp::fake([
    'bad text'   => Result::withMatches(['fuck']),
    'clean text' => Result::none('clean text'),
]);

$result = Blasp::check('bad text');
$result->isOffensive(); // true

// Assertions
Blasp::assertChecked();
Blasp::assertCheckedTimes(1);
Blasp::assertCheckedWith('bad text');
```

--------------------------------

### POST /allow

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Adds words to the allow list, which will not be considered offensive.

```APIDOC
## [POST] /allow

### Description
Adds words to the allow list, which will not be considered offensive.

### Method
POST

### Endpoint
/allow

### Parameters
#### Request Body
- **words** (array of strings) - Required - List of words to allow.
- **text** (string) - Required - The text to check.

### Request Example
{
  "words": ["damn", "hell"],
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /strict

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Forces the regex driver for strict checking.

```APIDOC
## [POST] /strict

### Description
Forces the regex driver for strict checking.

### Method
POST

### Endpoint
/strict

### Parameters
#### Request Body
- **text** (string) - Required - The text to check.

### Request Example
{
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /withSeverity

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Filters results by minimum severity level.

```APIDOC
## [POST] /withSeverity

### Description
Filters results by minimum severity level.

### Method
POST

### Endpoint
/withSeverity

### Parameters
#### Request Body
- **severity** (enum) - Required - The minimum severity level (e.g., High, Moderate).
- **text** (string) - Required - The text to check.

### Request Example
{
  "severity": "High",
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /english

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shorthand for setting the language to English.

```APIDOC
## [POST] /english

### Description
Shorthand for setting the language to English.

### Method
POST

### Endpoint
/english

### Parameters
#### Request Body
- **text** (string) - Required - The text to check.

### Request Example
{
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /lenient

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Forces the pattern driver for lenient checking.

```APIDOC
## [POST] /lenient

### Description
Forces the pattern driver for lenient checking.

### Method
POST

### Endpoint
/lenient

### Parameters
#### Request Body
- **text** (string) - Required - The text to check.

### Request Example
{
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### Stringable::isProfane

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Fluent Stringable macro to check for profanity.

```APIDOC
## Stringable::isProfane

### Description
Fluent method on Stringable to check if the string contains profanity.

### Signature
```php
Str::of(string $text)->isProfane(): bool
```

### Parameters
- **$text** (string) - Required - The text to check.

### Return Value
- **bool** - `true` if profanity is detected, `false` otherwise.

### Example
```php
Str::of('fuck this')->isProfane(); // true
```
```

--------------------------------

### Stringable::cleanProfanity

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Fluent Stringable macro to clean profanity and support chaining.

```APIDOC
## Stringable::cleanProfanity

### Description
Fluent method on Stringable to replace profanity with a mask. Returns a new Stringable instance, allowing chaining.

### Signature
```php
Str::of(string $text)->cleanProfanity(): Stringable
```

### Parameters
- **$text** (string) - Required - The text to clean.

### Return Value
- **Stringable** - A new Stringable instance with profanity masked.

### Example
```php
Str::of('fuck this')->cleanProfanity(); // Stringable('**** this')
Str::of('hello')->cleanProfanity()->upper(); // 'HELLO'
```
```

--------------------------------

### POST /german

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shorthand for setting the language to German.

```APIDOC
## [POST] /german

### Description
Shorthand for setting the language to German.

### Method
POST

### Endpoint
/german

### Parameters
#### Request Body
- **text** (string) - Required - The text to check.

### Request Example
{
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /mask

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Sets the masking style for offensive words.

```APIDOC
## [POST] /mask

### Description
Sets the masking style for offensive words.

### Method
POST

### Endpoint
/mask

### Parameters
#### Request Body
- **mask** (string or function) - Required - The mask character, 'grawlix', or a callback function.
- **text** (string) - Required - The text to check.

### Request Example
{
  "mask": "*",
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /spanish

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shorthand for setting the language to Spanish.

```APIDOC
## [POST] /spanish

### Description
Shorthand for setting the language to Spanish.

### Method
POST

### Endpoint
/spanish

### Parameters
#### Request Body
- **text** (string) - Required - The text to check.

### Request Example
{
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /inAllLanguages

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Checks the text against all available languages.

```APIDOC
## [POST] /inAllLanguages

### Description
Checks the text against all available languages.

### Method
POST

### Endpoint
/inAllLanguages

### Parameters
#### Request Body
- **text** (string) - Required - The text to check.

### Request Example
{
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /french

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shorthand for setting the language to French.

```APIDOC
## [POST] /french

### Description
Shorthand for setting the language to French.

### Method
POST

### Endpoint
/french

### Parameters
#### Request Body
- **text** (string) - Required - The text to check.

### Request Example
{
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### POST /block

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Adds custom words to the block list, which will be considered offensive.

```APIDOC
## [POST] /block

### Description
Adds custom words to the block list, which will be considered offensive.

### Method
POST

### Endpoint
/block

### Parameters
#### Request Body
- **words** (array of strings) - Required - List of custom words to block.
- **text** (string) - Required - The text to check.

### Request Example
{
  "words": ["customword"],
  "text": "..."
}

### Response
#### Success Response (200)
Same as /check response.
```

--------------------------------

### Per-model overrides

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Override the default mode, language, and mask per model using $blaspMode, $blaspLanguage, and $blaspMask properties.

```php
class Comment extends Model
{
    use Blaspable;

    protected array $blaspable = ['body', 'title'];
    protected string $blaspMode = 'reject';     // 'sanitize' (default) | 'reject'
    protected string $blaspLanguage = 'spanish'; // null = config default
    protected string $blaspMask = '#';           // null = config default
}
```

--------------------------------

### POST /checkMany

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Checks multiple text strings in a single call and returns an array of result objects.

```APIDOC
## [POST] /checkMany

### Description
Checks multiple text strings in a single call and returns an array of result objects.

### Method
POST

### Endpoint
/checkMany

### Parameters
#### Request Body
- **texts** (array of strings) - Required - An array of text strings to check.

### Request Example
{
  "texts": ["text one", "text two"]
}

### Response
#### Success Response (200)
- **results** (array) - Array of result objects, each with the same structure as a single check result.

#### Response Example
[
  {
    "isOffensive": false,
    "clean": "text one",
    "original": "text one",
    "score": 0,
    "count": 0,
    "uniqueWords": [],
    "severity": "None"
  },
  {
    "isOffensive": true,
    "clean": "text ****",
    "original": "text two",
    "score": 20,
    "count": 1,
    "uniqueWords": ["two"],
    "severity": "Moderate"
  }
]
```

--------------------------------

### Clear caches with artisan command

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Clears both dictionary and result caches using the artisan command. This is useful after configuration changes or when you need to invalidate cached data.

```bash
php artisan blasp:clear
```

--------------------------------

### Caching check() results

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Demonstrates that check() results are cached by default. The first call runs full analysis and caches the result; the second call returns the cached result instantly.

```php
// First call — runs full analysis, caches result
$result = Blasp::check('some text');

// Second call — returns cached result
$result = Blasp::check('some text');
```

--------------------------------

### Use Str and Stringable macros for profanity checking and cleaning

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Use Blasp's macros on Laravel's Str and Stringable classes to check for profanity and clean it. Static methods return booleans or cleaned strings; fluent methods return Stringable instances and support chaining.

```php
use Illuminate\Support\Str;

// Static methods
Str::isProfane('fuck this');        // true
Str::isProfane('hello');            // false
Str::cleanProfanity('fuck this');   // '**** this'
Str::cleanProfanity('hello');       // 'hello'

// Fluent Stringable methods
Str::of('fuck this')->isProfane();          // true
Str::of('fuck this')->cleanProfanity();     // Stringable('**** this')
Str::of('hello')->cleanProfanity()->upper(); // 'HELLO' (chaining works)
```

--------------------------------

### POST /check

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

The primary method to check a single text string for offensive language. Returns a result object with methods to inspect the outcome.

```APIDOC
## [POST] /check

### Description
Checks a single text string for offensive language and returns a result object with methods to inspect the outcome.

### Method
POST

### Endpoint
/check

### Parameters
#### Request Body
- **text** (string) - Required - The text to check for offensive language.

### Request Example
{
  "text": "This is a fucking sentence"
}

### Response
#### Success Response (200)
- **isOffensive** (boolean) - Whether the text contains offensive language.
- **clean** (string) - The text with offensive words masked.
- **original** (string) - The original text.
- **score** (integer) - A severity score.
- **count** (integer) - Number of offensive words found.
- **uniqueWords** (array) - List of unique offensive words.
- **severity** (enum) - Severity level (e.g., High).

#### Response Example
{
  "isOffensive": true,
  "clean": "This is a ******* sentence",
  "original": "This is a fucking sentence",
  "score": 30,
  "count": 1,
  "uniqueWords": ["fucking"],
  "severity": "High"
}
```

--------------------------------

### Result Object

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Documentation for the Result object returned by every check() call, listing all its methods and their return types.

```APIDOC
## Result Object

### Description
The `Result` object is returned by every `check()` call and provides methods to inspect the profanity detection results.

### Methods

#### `isOffensive()`
- **Returns**: `bool`
- **Description**: Text contains profanity

#### `isClean()`
- **Returns**: `bool`
- **Description**: Text is clean

#### `clean()`
- **Returns**: `string`
- **Description**: Text with profanities masked

#### `original()`
- **Returns**: `string`
- **Description**: Original unmodified text

#### `score()`
- **Returns**: `int`
- **Description**: Severity score (0-100)

#### `count()`
- **Returns**: `int`
- **Description**: Total profanity matches

#### `uniqueWords()`
- **Returns**: `array`
- **Description**: Unique base words detected

#### `severity()`
- **Returns**: `?Severity`
- **Description**: Highest severity in matches

#### `words()`
- **Returns**: `Collection`
- **Description**: `MatchedWord` objects with position, length, severity

#### `toArray()`
- **Returns**: `array`
- **Description**: Full result as array

#### `toJson()`
- **Returns**: `string`
- **Description**: Full result as JSON

### Notes
`Result` implements `JsonSerializable`, `Stringable` (returns clean text), and `Countable`.
```

--------------------------------

### Str::cleanProfanity

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Static macro on Laravel's Str class to replace profanity with a mask.

```APIDOC
## Str::cleanProfanity

### Description
Replaces profanity in a string with the configured mask character.

### Signature
```php
Str::cleanProfanity(string $text): string
```

### Parameters
- **$text** (string) - Required - The text to clean.

### Return Value
- **string** - The cleaned string with profanity masked.

### Example
```php
Str::cleanProfanity('fuck this'); // '**** this'
Str::cleanProfanity('hello');     // 'hello'
```
```

--------------------------------

### Reject mode exception handling

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

In reject mode, saving a model with profanity throws ProfanityRejectedException and the model is not persisted. Access the attribute, result, and unsaved model via the exception.

```php
use Blaspsoft\Blasp\Exceptions\ProfanityRejectedException;

try {
    $comment = Comment::create(['body' => 'profane text']);
} catch (ProfanityRejectedException $e) {
    $e->attribute; // 'body'
    $e->result;    // Result instance
    $e->model;     // The unsaved model
}
```

--------------------------------

### Listen to ModelProfanityDetected event

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

The ModelProfanityDetected event fires whenever profanity is detected on a model attribute, in both sanitize and reject modes. Access the model, attribute, and result from the event.

```php
use Blaspsoft\Blasp\Events\ModelProfanityDetected;

Event::listen(ModelProfanityDetected::class, function ($event) {
    $event->model;     // The model instance
    $event->attribute; // Which attribute had profanity
    $event->result;    // Result instance
});
```

--------------------------------

### Str::isProfane

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Static macro on Laravel's Str class to check if a string contains profanity.

```APIDOC
## Str::isProfane

### Description
Checks if a string contains profanity.

### Signature
```php
Str::isProfane(string $text): bool
```

### Parameters
- **$text** (string) - Required - The text to check.

### Return Value
- **bool** - `true` if profanity is detected, `false` otherwise.

### Example
```php
Str::isProfane('fuck this'); // true
Str::isProfane('hello');     // false
```
```

--------------------------------

### @clean Blade Directive

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Blade directive for sanitizing and escaping text in views.

```APIDOC
## @clean Blade Directive

### Description
Sanitizes and escapes text for safe display in views. Output is HTML-escaped via `e()` for XSS safety.

### Usage
```blade
<p>@clean($comment->body)</p>
```

### Equivalent
```php
{{ app('blasp')->check($comment->body)->clean() }}
```
```

--------------------------------

### Use fluent Profanity rule object

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Shows the fluent rule object for validation, allowing specification of language, severity, and maximum score. Uses the Profanity class and Severity enum.

```php
use Blaspsoft\Blasp\Rules\Profanity;
use Blaspsoft\Blasp\Enums\Severity;

$request->validate([
    'comment' => ['required', Profanity::in('english')],
    'bio'     => ['required', Profanity::severity(Severity::High)],
    'tagline' => ['required', Profanity::maxScore(50)],
]);
```

--------------------------------

### Clear dictionary cache programmatically

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Clears the dictionary cache programmatically using Dictionary::clearCache(). Note that result caching is automatically bypassed when using a CallbackMask because closures cannot be serialized.

```php
Dictionary::clearCache();
```

--------------------------------

### Disable Profanity Filtering

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Wrap code in Blasp::withoutFiltering() to disable profanity filtering, causing all checks to return clean results.

```php
Blasp::withoutFiltering(function () {
    // All checks return clean results
});
```

--------------------------------

### Use @clean Blade directive to sanitize and escape text

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Use the @clean directive in Blade views to sanitize and escape text for safe display. The output is HTML-escaped via e() for XSS safety.

```blade
<p>@clean($comment->body)</p>

{{-- Equivalent to: {{ app('blasp')->check($comment->body)->clean() }} --}}
```

--------------------------------

### Use Blaspable trait on a model

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Add the Blaspable trait to an Eloquent model and define the attributes to check via the $blaspable property.

```php
use Blaspsoft\Blasp\Blaspable;

class Comment extends Model
{
    use Blaspable;

    protected array $blaspable = ['body', 'title'];
}
```

--------------------------------

### Disable profanity checking

Source: https://github.com/blaspsoft/blasp/blob/main/README.md

Temporarily disable profanity checking for a model using withoutBlaspChecking().

```php
Comment::withoutBlaspChecking(function () {
    Comment::create(['body' => 'unchecked content']);
});
```
Tokens:
Raw