Download the PHP package niclas-timm/blacklister without Composer
On this page you can find all versions of the php package niclas-timm/blacklister. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download niclas-timm/blacklister
More information about niclas-timm/blacklister
Files in niclas-timm/blacklister
Package blacklister
Short Description Validate emails against a blacklist in your Laravel application
License MIT
Informations about the package 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
Install the package via composer:
Next, run the following command to boostrap the necessary configuration:
This does a few things:
- It creates a
config/blacklister.php
file - 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
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 blacklister is super easy. Just add the blacklist
keyword to your validation and you're ready to block! Like so:
👀 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:
➕ Adding new values to the blacklist
You can either paste the values directly into the JSON file, or use the following utility command:
Argument | Description | Examples |
---|---|---|
values | The values you want to add to the blacklist. Multiple values are allowed. | [email protected] , [email protected] [email protected] |
type | The type of values you want to add to the blacklist (emails or domains ). Defaults to emails . |
--type="emails" ,--type="domains" |
For example:
➖ Removing values from the blacklist
You can either remove the values directly into the JSON file, or use the following utility command:
Argument | Description | Examples |
---|---|---|
values | The values you want to remove from the blacklist. Multiple values are allowed. | [email protected] , [email protected] [email protected] |
For example:
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
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
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:
[!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 addphp artian blacklister:update-cache
to your deployment script.
💾 Exporting to CSV
You can export your blacklist to a csv file by executing the following command
Where filename
is the path to the csv file you want to export your blacklist to.
For example:
💽 Importing from csv
Need to import your blacklist from a csv file? No problem. Just execute
Where file
is the path to the csv file you want to import your blacklist from.
Example:
[!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
During the installation process, Blacklister creates the config/blacklister.php
file for you, which defines how
blacklister behaves.
Name | Type | Description | Example |
---|---|---|---|
blacklist_path | string | The absolute path to your blacklist file. | storage_path('framework/email_blacklist.json') |
enable_cache | boolean | If true, the content of the blacklist json file will be cached. | true |
cache_key | string | Defines under which cache key the data will be cached (if cache is enabled). | 'blacklist' |
cache_ttl | int | The time in minutes for how long the blacklist will be cached (if cache is enabled). | 60 * 24 * 4 (4 days) |
validation_message | string | The validation message that will be displayed if the validation fails (is translatable by default). | 'The value is not allowed. Please use another one.' |
enable_cookies | bool | If 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_name | string | The name of the cookie that will be set. | blacklister |
cookie_ttl | int | The 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:
😎 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.