Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

DNS Blacklist Plugin

The DNS Blacklist Plugin is an extension for Grav CMS. Checks an IP address via mutliple DNS Blacklists to see if it's banned. This serves as a transparent alternative to standard CAPTCHA solutions. It can be used as a PHP function, Twig function as well as via a Form action. Please see Important usage considerations and Blacklist providers sections below to better understand how and where to use the plugin and the options available.


Installing the DNS Blacklist plugin can be done in one of three ways: The GPM (Grav Package Manager) installation method lets you quickly install the plugin with a simple terminal command, the manual method lets you do so via a zip file, and the admin method lets you do so via the Admin Plugin.

GPM Installation (Preferred)

To install the plugin via the GPM, through your system's terminal (also called the command line), navigate to the root of your Grav-installation, and enter:

bin/gpm install dns-blacklist

This will install the DNS Blacklist plugin into your /user/plugins-directory within Grav. Its files can be found under /your/site/grav/user/plugins/dns-blacklist.

Admin Plugin

If you use the Admin Plugin, you can install the plugin directly by browsing the Plugins-menu and clicking on the Add button.


If you are not using the admin, you should copy the user/plugins/dns-blacklist/dns-blacklist.yaml to user/config/plugins/dns-blacklist.yaml and only edit that copy.

Here is the default configuration and an explanation of available options:

enabled: true

There are many blacklist providers available, please check out the Blacklist Providers section below for more details.

Note that if you use the Admin Plugin, a file with your configuration named dns-blacklist.yaml will be saved in the user/config/plugins/-folder once the configuration is saved in the Admin.


PHP Usage

You can use this plugin in your own plugin or theme specific PHP code by accessing it via the global Grav object. For example:

$blacklisted = Grav::instance()['dns-blacklist']->isBlacklisted();
if (!empty($blacklisted)) {
    echo "Your IP is blacklisted by: " . json_encode($blacklisted);
} else {
    echo "Your IP is good!";

You can also pass in a specific IP address to check:

$blacklisted = Grav::instance()['dns-blacklist']->isBlacklisted('');

Twig Usage

Very similar to the PHP usage, you can use the same blacklist class via Twig. Notice the name is dns_blacklist compared to dns-blacklist from regular PHP to make it more Twig-friendly:

{% if dns_blacklist.isBlacklisted  %}
  <h2 class="Error">Your IP is blacklisted, no form for you!</h2>
{% else %}
  {% include "forms/form.html.twig" with {form: forms('contact-form')} %}
{% endif %}

Form Action Usage

You can also use this logic directly in a form action, so that it's checked during form submission. For example, this is a sample page which defines a very simple form and simply checks for blacklisted IPs.

title: 'DNS Blacklist Test'
    name: dns-blacklist-test
            label: Name
            placeholder: Name
            type: text
                required: true
            type: submit
            html: true
            value: Submit
        dns-blacklist: true
        message: '<b>Thanks!</b> All good'

# IP Blacklist Testing

This is a simple blacklisting form action test page.

To create a quick IP checker form you can adapt this form:

title: 'DNS Blacklist Checker'
    name: dns-blacklist-checker
            label: IP Address to Check
            type: text
                required: true
            type: submit
            value: Submit
        dns-blacklist: "{{ form.value.ip }}"
        message: '<b>Thanks!</b> All good'

# IP Blacklist Testing

If you want to provide a custom error message instead of one that references the IP address and the DNSBL providers that block it, you can simply add a custom message in the form_error: property of the configuration yaml.

Important usage considerations

Although there are different methods to invoke the blacklist check, please note that using the plugin during form validation may be required for older websites where the form location is already known to spammers and has been abused in the past. In those cases spam IPs will simply issue a direct POST request, thereby subverting any form display logic in Twig templates. Using both Twig and Form methods at the same time may be the best approach for all websites. Twig method will hide your form from form-harvesting robots and Form method will prevent abusing the form by those who are already aware of it.

There's also a small chance of a false positive, that is, a legitimate visitor having a "spammy" blacklisted IP. That's why it's also important to use the Twig method to avoid frustrating the user with an error after they'd already spent time filling your form.

Blacklist Providers

The default list was specifically handpicked to avoid blacklisting legitimate IP addresses. The reason you shouldn't be using just any blacklist is because those are very likely by default to include all regular dynamic IP addresses and those should never be blocked for that reason alone. Most of the blacklists exist to serve e-mail server administrators where accepting mail from dynamic IPs or IPs with misconfigured DNS entires is undesireable regardless of whether or not they are confirmed sources of spam. Example of such a composite blacklist that you shouldn't be using for forms is as it includes their PBL blacklist. Composite blacklists should always be avoided. When using blacklists you'll be wanting to only filter IP addresses that are caught actively sending spam, participating in botnets and those infected with spam-related malware. Not all of blacklist operators provide documentation to help you understand what exactly is being filtered, so when in doubt – stick to the defaults


A simple yet useful Grav plugin to check if an IP address is DNS Blacklisted







No packages published