Banhammer, a Model and IP ban package for Laravel

Banhammer for Laravel offers a very simple way to ban any Model by ID and by IP. It also allows to block requests by IP addresses.

Banned models can have an expiration date and will be automatically unbanned using the Scheduler.

Version Compatibility

Laravel	Banhammer
^9.0	1.x.x
^10.0	1.x.x

Installation

You can install the package via composer:

composer require mchev/banhammer

Then run the migrations with:

php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="banhammer-config"

It is possible to define the table name and the fallback_url in the config/ban.php file.

Usage

To make a model bannable, add the Mchev\Banhammer\Traits\Bannable trait to the model:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Mchev\Banhammer\Traits\Bannable;

class User extends Authenticatable
{
    use Bannable;
}

You can add the Bannable trait on as many models as you want (Team, Group, User, etc.).

Ban / Unban

Simple ban

$user->ban();

IP Ban

$user->ban([
	'ip' => $user->ip,
]);

Full

All attributes are optional

$model->ban([
	'created_by_type' => 'App\Models\User',
	'created_by_id' => 1,
	'comment' => "You've been evil",
	'ip' => "8.8.8.8",
	'expired_at' => Carbon::now()->addDays(7)
]);

Shorthand

$user->banUntil('2 days');

List model bans

$bans = $model->bans();

Check if model is banned.

You can create custom middlewares using these methods.

$model->isBanned();
$model->isNotBanned();

Filters

$bannedTeams = Team::banned()->get(); 
$notBannedTeams = Team::notBanned()->get();

Unban

$user->unban();

IP

Ban IPs

use Mchev\Banhammer\IP;

IP::ban("8.8.8.8");
IP::ban(["8.8.8.8", "4.4.4.4"]);

Unban IPs

use Mchev\Banhammer\IP;

IP::unban("8.8.8.8");
IP::unban(["8.8.8.8", "4.4.4.4"]);

List all banned IPs

use Mchev\Banhammer\IP;

$ips = IP::banned()->get(); // Collection
$ips = IP::banned()->pluck('ip')->toArray(); // Array

Middleware

To prevent banned users from accessing certain parts of your application, simply add the auth.banned middleware on the concerned routes.

Route::middleware(['auth.banned'])->group(function () {
    // ...
});

To prevent banned ips from accessing certain parts of your application, simply add the ip.banned middleware on the concerned routes.

Route::middleware(['ip.banned'])->group(function () {
    // ...
});

To block and logout banned Users or IP, add the logout.banned middleware:

Route::middleware(['logout.banned'])->group(function () {
    // ...
});

If you use the logout.banned middleware, it is not necessary to cumulate the other middlewares.

If you want to block IPs on every HTTP request of your application, list Mchev\Banhammer\Middleware\IPBanned in the $middleware property of your app/Http/Kernel.php class.

Scheduler

⚠ IMPORTANT

In order to be able to automatically delete expired bans, you must have a cron job set up on your server to run the Laravel Scheduled Jobs

Running the scheduler

Configure Scheduler on Forge

Events

If entity is banned Mchev\Banhammer\Events\ModelWasBanned event is fired.

Is entity is unbanned Mchev\Banhammer\Events\ModelWasUnbanned event is fired.

MISC

To manually unban expired bans :

use Mchev\Banhammer\Banhammer;

Banhammer::unbanExpired();

Or you can use the command:

php artisan banhammer:unban

To permanently delete all the expired bans :

use Mchev\Banhammer\Banhammer;

Banhammer::clear();

Or you can use the command:

php artisan banhammer:clear

Testing

composer test

artmeet/banhammer

Banhammer, a Model and IP ban package for Laravel

Version Compatibility

Installation

Usage

Ban / Unban

IP

Middleware

Scheduler

Events

MISC

Testing

Changelog

Roadmap

Contributing

Security Vulnerabilities

Credits

License