PHPackages                             elegantly/laravel-banhammer - 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. [Authentication & Authorization](/categories/authentication)
4. /
5. elegantly/laravel-banhammer

ActiveLibrary[Authentication & Authorization](/categories/authentication)

elegantly/laravel-banhammer
===========================

Ban any model in your Laravel App

v1.1.1(3mo ago)11.5k↓30%[1 PRs](https://github.com/ElegantEngineeringTech/laravel-banhammer/pulls)MITPHPPHP ^8.3CI passing

Since May 16Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/ElegantEngineeringTech/laravel-banhammer)[ Packagist](https://packagist.org/packages/elegantly/laravel-banhammer)[ Docs](https://github.com/elegantly/laravel-banhammer)[ GitHub Sponsors](https://github.com/ElegantEngineeringTech)[ RSS](/packages/elegantly-laravel-banhammer/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (12)Versions (8)Used By (0)

Laravel Banhammer
=================

[](#laravel-banhammer)

**Laravel Banhammer** is a robust, flexible solution for managing model bans (Users, Teams, Organizations, etc.) with support for ban levels, expiration dates, and performance-optimized querying.

Key Features
------------

[](#key-features)

- **Polymorphic:** Ban any Eloquent model.
- **Time-aware:** Support for permanent or temporary bans.
- **Tiered Restrictions:** Use "levels" to define the severity of the ban.
- **Performance First:** Includes a denormalization command to keep your queries fast.

---

Installation
------------

[](#installation)

Install the package via composer:

```
composer require elegantly/laravel-banhammer
```

### 1. Configure Your Models

[](#1-configure-your-models)

Publish the configuration file:

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

In `config/banhammer.php`, list the models that can be banned:

```
return [
    'model_ban' => Elegantly\Banhammer\Models\Ban::class,

    'bannables' => [
        \App\Models\User::class,
        \App\Models\Team::class,
    ],
];
```

### 2. Migrations

[](#2-migrations)

Publish and run the migrations:

```
php artisan vendor:publish --tag="banhammer-migrations"
php artisan migrate
```

### 3. Schedule the Denormalizer

[](#3-schedule-the-denormalizer)

This package uses a denormalization strategy to ensure checking a user's ban status doesn't require a heavy database join every time.

Add the command to your `routes/console.php`:

```
use Illuminate\Support\Facades\Schedule;
use Elegantly\Banhammer\Commands\DenormalizeBannableCommand;

// This updates the 'is_banned' status on your models based on ban expiration dates
Schedule::command(DenormalizeBannableCommand::class)->everyMinute();
```

---

Usage
-----

[](#usage)

### Preparing the Model

[](#preparing-the-model)

Implement the `BannableContract` and use the `Bannable` trait in any model you wish to restrict:

```
namespace App\Models;

use Elegantly\Banhammer\Models\Concerns\Bannable;
use Elegantly\Banhammer\Models\Contracts\BannableContract;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements BannableContract
{
    use Bannable;
}
```

### Banning a Model

[](#banning-a-model)

You can specify the severity (level), the reason, and the duration.

```
$user = User::find(1);

// Ban indefinitely
$user->ban(
    level: 0,
    reason: "Repeated spamming",
);

// Ban until a specific date (Temporary)
$user->ban(
    level: 1,
    reason: "Cooling off period",
    until: now()->addDays(7)
);
```

### Checking Ban Status

[](#checking-ban-status)

The package provides helpful methods to check if a model is currently restricted.

```
// Check if currently banned
if ($user->isBanned()) {
    return response()->json(['error' => 'Your account is suspended.'], 403);
}

if ($user->isBanned(1)) { // $user->ban_level >= 1
    // Restricted from specific high-level actions
}

// Check for a specific ban level
if ($user->ban_level === 1) {
    // Restricted from specific high-level actions
}
```

### Unbanning

[](#unbanning)

To lift all bans from a model:

```
$user->unban();
```

---

Testing
-------

[](#testing)

```
composer test
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://www.google.com/search?q=CONTRIBUTING.md) for details.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance86

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 74.2% 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 ~54 days

Recently: every ~67 days

Total

6

Last Release

90d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d769563728757858e249f266ac2555f28db5640124df92821ed17d93ee76fc7b?d=identicon)[QuentinGab](/maintainers/QuentinGab)

---

Top Contributors

[![QuentinGab](https://avatars.githubusercontent.com/u/40128136?v=4)](https://github.com/QuentinGab "QuentinGab (23 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (6 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")

---

Tags

laravelElegantlylaravel-banhammer

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/elegantly-laravel-banhammer/health.svg)

```
[![Health](https://phpackages.com/badges/elegantly-laravel-banhammer/health.svg)](https://phpackages.com/packages/elegantly-laravel-banhammer)
```

###  Alternatives

[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k89.8M1.0k](/packages/spatie-laravel-permission)[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k2.9M88](/packages/bezhansalleh-filament-shield)[jeffgreco13/filament-breezy

A custom package for Filament with login flow, profile and teams support.

1.0k1.7M41](/packages/jeffgreco13-filament-breezy)[spatie/laravel-login-link

Quickly login to your local environment

4381.2M1](/packages/spatie-laravel-login-link)[ryangjchandler/laravel-cloudflare-turnstile

A simple package to help integrate Cloudflare Turnstile.

438896.6k2](/packages/ryangjchandler-laravel-cloudflare-turnstile)[spatie/laravel-passkeys

Use passkeys in your Laravel app

444494.4k16](/packages/spatie-laravel-passkeys)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)