PHPackages milenmk/laravel-blacklist - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Validation & Sanitization](/categories/validation) 4. / 5. milenmk/laravel-blacklist ActiveLibrary[Validation & Sanitization](/categories/validation) milenmk/laravel-blacklist ========================= A Laravel package for blacklist validation of user input 1.4.0(4mo ago)251↓50%MITPHPPHP ^8.0 Since Apr 26Pushed 4mo ago1 watchersCompare [ Source](https://github.com/milenmk/laravel-blacklist)[ Packagist](https://packagist.org/packages/milenmk/laravel-blacklist)[ RSS](/packages/milenmk-laravel-blacklist/feed)WikiDiscussions develop Synced 1mo ago READMEChangelog (5)Dependencies (7)Versions (6)Used By (0) Laravel Blacklist ================= [](#laravel-blacklist) [![Latest Version on Packagist](https://camo.githubusercontent.com/d76430982e52bfda408eaf59288326be8c796a0390afb3030d7a82dfecae18e2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d696c656e6d6b2f6c61726176656c2d626c61636b6c6973742e7376673f7374796c653d666c6174)](https://packagist.org/packages/milenmk/laravel-blacklist)[![Total Downloads](https://camo.githubusercontent.com/853e5e1e8c62f8474262f7ff376a0462ffc39402d135876ce909f6fac5daa1b4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d696c656e6d6b2f6c61726176656c2d626c61636b6c6973742e7376673f7374796c653d666c6174)](https://packagist.org/packages/milenmk/laravel-blacklist)[![GitHub User's stars](https://camo.githubusercontent.com/e51f5d3362a1de9325cf0aa5c25d7bc92f56403aebba29e77f16cebcc22c7215/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f6d696c656e6d6b2f6c61726176656c2d626c61636b6c697374)](https://github.com/milenmk/laravel-blacklist)[![Laravel 10 Support](https://camo.githubusercontent.com/0b7f902482de7d3663b7aa6b87b7caca6e7b3fed489112e6f65f79f4514e60de/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e7825374331312e7825374331322e782d6f72616e67653f7374796c653d666c6174266c6f676f3d6c61726176656c)](https://laravel.com/docs)[![PHP Version Support](https://camo.githubusercontent.com/53256e6b98696db7e42809a84b15bd5cb3256e258724f01fb8a1ca2e57ea7adf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6d696c656e6d6b2f6c61726176656c2d626c61636b6c6973743f7374796c653d666c6174)](https://www.php.net)[![License](https://camo.githubusercontent.com/d33d94527f8c78a9751f011396724b9cc7f357d92e01e3f597809eb9dcb12c96/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d696c656e6d6b2f6c61726176656c2d626c61636b6c6973742e7376673f7374796c653d666c6174)](https://github.com/milenmk/laravel-blacklist/blob/develop/LICENSE.md)[![Contributions Welcome](https://camo.githubusercontent.com/9e93e892d0685e1bf7a1d0bd7c8410d6ecf2086a0a7b48dd58a6b96fa556ea2a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f6e747269627574696f6e732d77656c636f6d652d627269676874677265656e2e7376673f7374796c653d666c6174)](https://github.com/milenmk/laravel-blacklist/issues)[![Sponsor me](https://camo.githubusercontent.com/2aff1b5ae52a46452f3284b52645e299f456561d4dfd9b4d20d0a00a8351a123/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53706f6e736f722d2545322539442541342d6666363962343f7374796c653d666c6174)](https://www.patreon.com/c/LaravelAddonsbyMilen) Laravel Blacklist: 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: ------------- [](#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 ------------ [](#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 [](#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 ----- [](#usage) #### Basic controller [](#basic-controller) ``` use Milenmk\LaravelBlacklist\Services\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 [](#livewire-component) ``` use Livewire\Component; use Milenmk\LaravelBlacklist\Services\BlacklistService; class YourComponent extends Component { protected BlacklistService $blacklistService; public function mount(): void { $this->blacklistService = app(BlacklistService::class); } ``` #### Livewire form [](#livewire-form) ``` use Livewire\Form; use Milenmk\LaravelBlacklist\Services\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 -------------- [](#advanced-usage) ### 1. Blacklist Validation Rule [](#1-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')], ]; } ``` ### 2. Route Middleware [](#2-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'); ``` ### 3. Whitelist and Ignore Patterns [](#3-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+$/'], ``` ### 4. Advanced Matching Strategies [](#4-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" ], ], ``` ### 5. Context-Aware Validation [](#5-context-aware-validation) Map different contexts (fields) to specific lists: ``` 'contexts' => [ 'username' => ['blacklist', 'strict_list'], 'comment' => ['profanity', 'typo_list', 'leet_list'], ], ``` ### Custom Log Channel [](#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 [](#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 [](#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) [](#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. Changelog --------- [](#changelog) Please see [CHANGELOG.md](CHANGELOG.md) for more information on what has changed recently. Support My Work --------------- [](#support-my-work) If this package saves you time, you can support ongoing development: 👉 [Become a Patron](https://www.patreon.com/c/LaravelAddonsbyMilen) Other Packages -------------- [](#other-packages) Check out my other Laravel packages: - **[Laravel GDPR Cookie Manager](https://packagist.org/packages/milenmk/laravel-gdpr-cookie-manager)** - GDPR-compliant cookie consent management with user preference tracking - **[Laravel Email Change Confirmation](https://packagist.org/packages/milenmk/laravel-email-change-confirmation)** - Secure email change confirmation system - **[Laravel GDPR Exporter](https://packagist.org/packages/milenmk/laravel-gdpr-exporter)** - GDPR-compliant data export functionality - **[Laravel Locations](https://packagist.org/packages/milenmk/laravel-locations)** - Add Countries, Cities, Areas, Languages and Currencies models to your Laravel application - **[Laravel Rate Limiting](https://packagist.org/packages/milenmk/laravel-rate-limiting)** - Advanced rate limiting capabilities with exponential backoff - **[Laravel Datatables and Forms](https://packagist.org/packages/milenmk/laravel-simple-datatables-and-forms)** - Easy to use package to create datatables and forms for Livewire components License ------- [](#license) This package is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for more details. Disclaimer ---------- [](#disclaimer) This package is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or noninfringement. The author(s) make no guarantees regarding the accuracy, reliability, or completeness of the code, and shall not be held liable for any damages or losses arising from its use. Please ensure you thoroughly test this package in your environment before deploying it to production. ### Health Score 38 — LowBetter than 85% of packages Maintenance75 Regular maintenance activity Popularity13 Limited adoption so far Community7 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~60 days Total 5 Last Release 140d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/a8b620564b17fda00eccd47bc8b4e61256537052c1b0f1f131e4196446a50fd0?d=identicon)[milenmk](/maintainers/milenmk) --- Top Contributors [![milenmk](https://avatars.githubusercontent.com/u/4587305?v=4)](https://github.com/milenmk "milenmk (18 commits)") --- Tags blacklistlaravellaravel-packageprofanity-filter ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/milenmk-laravel-blacklist/health.svg) ``` [![Health](https://phpackages.com/badges/milenmk-laravel-blacklist/health.svg)](https://phpackages.com/packages/milenmk-laravel-blacklist) ``` ### Alternatives [spatie/laravel-honeypot Preventing spam submitted through forms 1.6k6.0M60](/packages/spatie-laravel-honeypot)[proengsoft/laravel-jsvalidation Validate forms transparently with Javascript reusing your Laravel Validation Rules, Messages, and FormRequest 1.1k2.3M49](/packages/proengsoft-laravel-jsvalidation)[stevebauman/purify An HTML Purifier / Sanitizer for Laravel 5325.6M19](/packages/stevebauman-purify)[axlon/laravel-postal-code-validation Worldwide postal code validation for Laravel and Lumen 3853.3M1](/packages/axlon-laravel-postal-code-validation)[sunspikes/clamav-validator Custom Laravel 5 anti-virus validator for file uploads. 3651.8M3](/packages/sunspikes-clamav-validator)[laravel-validation-rules/credit-card Validate credit card number, expiration date, cvc 2412.2M5](/packages/laravel-validation-rules-credit-card) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)