Laravel Blacklist Documentation

A robust content filtering solution for Laravel applications that provides comprehensive validation against unwanted user input. This package offers dual-layer protection with both system blacklist words (preventing username squatting and system impersonation) and profanity/offensive terms filtering.

Key features:

• Intelligent Word Boundary Matching: Prevents false positives while catching problematic content.
• Flexible Filtering Modes: Use system blacklist only, profanity filtering only, or both simultaneously.
• Advanced Matching Strategies:
  • Exact: Whole word matching (default).
  • Fuzzy: Catch typos using Levenshtein distance (e.g., "admin" matches "adm1n").
  • Substitution: Catch "leet speak" substitutions (e.g., "h3ll0").
• Context-Aware Validation: Define different validation rules for different fields (e.g., stricter rules for usernames vs comments).
• Whitelist & Ignore Patterns: Globally whitelist terms or use regex to ignore specific patterns.
• Customizable Word Lists: Easily extend or modify lists via configuration.
• Detailed Error Messages: Users receive context-aware validation feedback.
• Built-in Security Logging: Support for custom log channels.
• Simple Integration: Works with Laravel controllers, Livewire components, and forms.
• Zero Dependencies: Lightweight and efficient.
• Optional Logging Support: Pass a custom log channel to capture violations or auditing.

Perfect for applications requiring content moderation, user registration systems, comment sections, or any user-generated content that needs protection against inappropriate language or system term abuse.

Installation

1. Install the package via composer:

   composer require milenmk/laravel-blacklist
   

2. Publish the configuration file

   The package works out of the box with default settings, but you can customize it by publishing the config file:

   php artisan vendor:publish --tag=blacklist-config
   

   This will create a config/blacklist.php file where you can:

   1. Choose which word lists to use (system blacklist, profanity, or both)
   2. Customize the blacklisted terms in each list

   Note: If you don't publish the config file, the package will use the default configuration with the 'blacklist' mode enabled.

3. Publish the package language file

   php artisan vendor:publish --tag=blacklist-translations
   

Configuration options

The package provides three modes for filtering content:

// config/blacklist.php
return [
    // Choose which lists to use: 'blacklist', 'profanity', or 'both'
    'mode' => 'blacklist',
    
    // System blacklist words (usernames, reserved terms, etc.)
    'blacklist' => [
        'admin',
        'system',
        // ...
    ],
    
    // Profanity and offensive terms
    'profanity' => [
        // Common profanity words
        // ...
    ],

    // Whitelist words that should never be flagged
    'whitelist' => [
        'Laravel',
    ],

    // Regex patterns to ignore
    'ignore_patterns' => [
        '/^uuid-.*$/', 
    ],

    // Advanced matching strategies
    'lists' => [
        'custom_list' => [
            'terms' => ['forbidden'],
            'matching' => 'fuzzy', // Options: exact, fuzzy, substitution
            'threshold' => 1,      // For fuzzy matching
        ],
    ],

    // Per-field contexts
    'contexts' => [
        'username' => ['blacklist', 'custom_list'],
    ],
];

Usage

Basic controller

use Milenmk\LaravelBlacklist\BlacklistService;

class YourController
{
    protected BlacklistService $blacklistService;
    
    public function __construct(BlacklistService $blacklistService)
    {
        $this->blacklistService = $blacklistService;
    }
    
    public function store(Request $request)
    {
        // Validate request...
        
        // Check fields against blacklisted words
        $blacklistErrors = $this->blacklistService->checkFields([
            'name' => $request->input('name'),
            'email' => $request->input('email'),
            // Add any other fields you want to check
        ]);
        
        if (!empty($blacklistErrors)) {
            return redirect()->back()->withErrors($blacklistErrors);
        }
        
        // Continue with your logic...
    }
}

Livewire component

use Livewire\Component;
use Milenmk\LaravelBlacklist\BlacklistService;

class YourComponent extends Component
{

    protected BlacklistService $blacklistService;

    public function mount(): void
    {
        $this->blacklistService = app(BlacklistService::class);
    }

Livewire form

use Livewire\Form;
use Milenmk\LaravelBlacklist\BlacklistService;

class YourForm extends Form
{
    protected BlacklistService $blacklistService;

    public function __construct($componentOrService = null, $propertyName = null)
    {

        parent::__construct($componentOrService, $propertyName);
        $this->blacklistService = app(BlacklistService::class);
    }
}

Advanced Usage

Blacklist Validation Rule

You can use the BlacklistRule in your form requests or validation logic.

use Milenmk\LaravelBlacklist\Rules\BlacklistRule;

// ...

public function rules(): array
{
    return [
        // Uses 'username' as the context (checks 'contexts.username' in config)
        'username' => ['required', new BlacklistRule()],
        
        // Explicitly specify the context
        'bio' => ['required', new BlacklistRule('strict_bio')],
    ];
}

Route Middleware

Protect your routes using the blacklist middleware.

// Protect a route using the 'comment' context
Route::post('/comments', ...)->middleware('blacklist:comment');

// If no context is provided, it uses the field names from the request as contexts
Route::post('/profile', ...)->middleware('blacklist');

Whitelist and Ignore Patterns

You can define global exceptions in your configuration file:

• Whitelist: Exact words that should never be blocked (e.g., "Analyst").
• Ignore Patterns: Regex patterns to ignore (e.g., ignoring UUIDs or specific codes).

// config/blacklist.php
'whitelist' => ['Analyst', 'Dickson'],
'ignore_patterns' => ['/^TX-\d+$/'],

Advanced Matching Strategies

You can define custom lists with specific matching strategies in config/blacklist.php:

'lists' => [
    'strict_list' => [
        'terms' => ['forbidden'],
        'matching' => 'exact',
    ],
    'typo_list' => [
        'terms' => ['important'],
        'matching' => 'fuzzy', // Uses Levenshtein distance
        'threshold' => 1,      // Matches "1mportant"
    ],
    'leet_list' => [
        'terms' => ['hacker'],
        'matching' => 'substitution', // Matches "h4ck3r"
    ],
],

Context-Aware Validation

Map different contexts (fields) to specific lists:

'contexts' => [
    'username' => ['blacklist', 'strict_list'],
    'comment' => ['profanity', 'typo_list', 'leet_list'],
],

Custom Log Channel

You can specify a custom log channel:

$blacklistErrors = $this->blacklistService->checkFields([
    'name' => $request->input('name'),
    'email' => $request->input('email'),
], 'security');

Switching Modes

You can change the filtering mode in your config file:

// config/blacklist.php
'mode' => 'blacklist', // Only check system blacklist words
// OR
'mode' => 'profanity', // Only check profanity/offensive words
// OR
'mode' => 'both',      // Check both lists

The error messages will indicate which list the matched term belongs to:

• "The {field} contains the blacklisted word: "{term}""
• "The {field} contains the profanity word: "{term}""

Word Matching

This package uses whole word boundary matching to prevent false positives. For example:

• "admin" will match in "admin user" but not in "administrator" or "badminton"
• "damn" will match in "that's damn good" but not in "condamnation"

This ensures that legitimate content isn't incorrectly flagged while still catching problematic terms.

Enhanced Attribute Name Support (New)

The checkFields() method now accepts an optional third parameter $attributes — an associative array mapping field names to human-readable labels:

$attributes = [
    'last_name' => 'Last Name',
    'name' => 'Name',
    'email' => 'Email Address',
    // Add your fields here
];

$blacklistErrors = $this->blacklistService->checkFields($input, null, $attributes);

This enables error messages to display friendly field names instead of raw input keys. For example:

The Last Name contains a blacklisted word: administrator

instead of

The last_name contains a blacklisted word: administrator

This ensures your error messages remain clear and consistent with Laravel's native validation attribute naming conventions, improving user experience.