PHPackages niclas-timm/blacklister - 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. niclas-timm/blacklister ActiveLibrary[Validation & Sanitization](/categories/validation) niclas-timm/blacklister ======================= Validate emails against a blacklist in your Laravel application 1.3.0(2y ago)1410.4k↑65.6%[5 issues](https://github.com/niclas-timm/blacklister/issues)MITPHP Since Nov 23Pushed 2y ago2 watchersCompare [ Source](https://github.com/niclas-timm/blacklister)[ Packagist](https://packagist.org/packages/niclas-timm/blacklister)[ RSS](/packages/niclas-timm-blacklister/feed)WikiDiscussions main Synced 2d ago READMEChangelog (4)Dependencies (2)Versions (7)Used By (0) 👮 Blacklister ============= [](#-blacklister) Blacklist is a package for **Laravel** applications that enables you to validate email inputs against a blacklist. You can block specific email addresses or entire domains. ⬇️ Installation --------------- [](#️-installation) Install the package via composer: ``` composer require niclas-timm/blacklister ``` Next, run the following command to boostrap the necessary configuration: ``` php artisan blacklister:install ``` This does a few things: 1. It creates a `config/blacklister.php` file 2. It creates a file named `storage/framework/blacklist.json`. This is where you store your blacklist. You can rename and relocate this file later, if you want to (see "Configuration" section). 🤙 Usage ------- [](#-usage) Blacklister uses a JSON file to store your blacklist. By default, this file is located under `storage/framework/blacklist.json`, but you can configure it to your needs (see below). In that file, two keys are required: `emails` and `domains`, which both expect arrays as their respective value. As the names suggest, you can use these to block individual email addresses or entire domains. ### ✅ Using the validation [](#-using-the-validation) Using blacklister is super easy. Just add the `blacklist` keyword to your validation and you're ready to block! Like so: ``` public function store(Request $request) { $validated = $request->validate([ 'email' => 'required|email|blacklist', ]); } ``` ### 👀 Viewing the blacklist [](#-viewing-the-blacklist) One way is of course to just look at your JSON file. Another way is to run the following command to view the blacklist in the console: ``` php artisan blacklister:view ``` ### ➕ Adding new values to the blacklist [](#-adding-new-values-to-the-blacklist) You can either paste the values **directly into the JSON file**, or use the following utility command: ``` php artisan blacklister:add {values} {--T|type} ``` ArgumentDescriptionExamplesvaluesThe values you want to add to the blacklist. Multiple values are allowed.`block@me.com`, `block@me.com leave-me@alone.com`typeThe type of values you want to add to the blacklist (`emails` or `domains`). Defaults to `emails`.`--type="emails"`,`--type="domains"`For example: ``` # Block emails. php artisan blacklister:add block@me.com leave-me@alone.com --type="emails" # Block domain. php artisan blacklister:add blockme.com --type="domains" ``` ### ➖ Removing values from the blacklist [](#-removing-values-from-the-blacklist) You can either remove the values **directly into the JSON file**, or use the following utility command: ``` php artisan blacklister:remove {values} ``` ArgumentDescriptionExamplesvaluesThe values you want to remove from the blacklist. Multiple values are allowed.`block@me.com`, `block@me.com leave-me@alone.com`For example: ``` php artisan blacklister:remove unblock@me.com i-am-not-dangerous.com ``` This command will automatically detect if the value is an individual email or a domain and remove the corresponding data from your blacklist file. ### 🍪 Using cookies [](#-using-cookies) Ok, so you blocked someone. Now what? They can just use another email address and register anyways, right? Wrong! You can set `enable_cookies` to `true` config file. Then, when a blacklister validation fails, a cookie will be set in the users browser. Afterward, every validation will fail for as long as the cookie is valid. So if the user tries to register with another email, it won't work. Obviously, this solution is not bulletproof. The user could use incognito mode or use another browser. But it's better than nothing. ### 🔄 Updating cache [](#-updating-cache) If the cache for Blacklister is enabled (see below), the values from the JSON file are cached. This means that you need to update the cache whenever the blacklist JSON file changes. If you use the `backlister:add` or `blacklister:remove` utility-commands, this happens automatically. If you update the JSON file manually, you need to execute the following command thereafter: ``` php artisan blacklister:update-cache ``` Warning You must **run this command on your production system** as well in order for the changes to take effect there. If you update your blacklist frequently, it might make sense to add `php artian blacklister:update-cache` to your deployment script. ### 💾 Exporting to CSV [](#-exporting-to-csv) You can export your blacklist to a csv file by executing the following command ``` php artisan blacklister:export {file} ``` Where `filename` is the path to the csv file you want to export your blacklist to. For example: ``` php artisan blacklister:export /my/export/directory/blacklister.csv ``` ### 💽 Importing from csv [](#-importing-from-csv) Need to import your blacklist from a csv file? No problem. Just execute ``` php artisan blacklister:import {file} ``` Where `file` is the path to the csv file you want to import your blacklist from. Example: ``` php artisan blacklister:import /my/import/directory/blacklister.csv ``` Warning Your csv file must have a specific format: It must have the headers "emails" and "domains". For an example file look at `/tests/fixtures/import_data.csv` ⚙️ Configuration ---------------- [](#️-configuration) During the installation process, Blacklister creates the `config/blacklister.php` file for you, which defines how blacklister behaves. NameTypeDescriptionExampleblacklist\_pathstringThe absolute path to your blacklist file.`storage_path('framework/email_blacklist.json')`enable\_cachebooleanIf true, the content of the blacklist json file will be cached.`true`cache\_keystringDefines under which cache key the data will be cached (if cache is enabled).`'blacklist'`cache\_ttlintThe time in minutes for how long the blacklist will be cached (if cache is enabled).`60 * 24 * 4` (4 days)validation\_messagestringThe validation message that will be displayed if the validation fails (is translatable by default).`'The value is not allowed. Please use another one.'`enable\_cookiesboolIf true, a cookie will be set when the blacklister validation fails. Afterwards, every validation will fail for as long as the cookie is valid.`true`cookie\_namestringThe name of the cookie that will be set.`blacklister`cookie\_ttlintThe time in seconds for how long the cookie will be valid.`60 * 24 * 30` (30 days)You can check if your configuration is valid by executing the following command: ``` php artisan blacklister:verify ``` 😎 How it works -------------- [](#-how-it-works) Blacklister is actually really simple. If cache is disabled, if fetches the content from the JSON file on every request and then checks if the individual email or the entire domain is on the blacklist. If cache is enabled, Blacklister first tries to retrieve the blacklist from the cache. If it doesn't find it, it loads the data from the JSON file and puts it into the cache, so it can be used the next time. ### Health Score 28 — LowBetter than 52% of packages Maintenance13 Infrequent updates — may be unmaintained Popularity33 Limited adoption so far Community8 Small or concentrated contributor base Maturity47 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 ~4 days Total 4 Last Release 941d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/381f10a1adac5e8795dba0dddf2186ee5fdff54d1a59e7e348f5db26fddf0950?d=identicon)[NiclasTimm](/maintainers/NiclasTimm) --- Top Contributors [![niclas-timm](https://avatars.githubusercontent.com/u/58849920?v=4)](https://github.com/niclas-timm "niclas-timm (22 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/niclas-timm-blacklister/health.svg) ``` [![Health](https://phpackages.com/badges/niclas-timm-blacklister/health.svg)](https://phpackages.com/packages/niclas-timm-blacklister) ``` ### Alternatives [marcosh/php-validation-dsl A DSL for validating data in a functional fashion 483.9k](/packages/marcosh-php-validation-dsl) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)