Download the PHP package mchev/banhammer without Composer

Banhammer 🔨

A simple and powerful ban package for Laravel - ban models, IPs, and countries with ease.

Banhammer allows you to ban any Eloquent model, IP addresses, and even entire countries. Bans can be permanent or temporary with automatic expiration.

📋 Table of Contents

• Quick Start
• Features
• Installation
• Usage Guide
  • Banning Models
  • Banning IPs
  • Country Blocking
  • Middleware
  • Scheduler
  • Events
• Advanced Topics
  • Metas
  • UUIDs
  • Upgrading
• Development

🚀 Quick Start

Add the trait to your model:

Ban a user:

✨ Features

• ✅ Ban any Eloquent model (User, Team, etc.)
• ✅ Ban IP addresses (single or multiple)
• ✅ Block entire countries
• ✅ Temporary or permanent bans
• ✅ Automatic expiration handling
• ✅ Middleware protection
• ✅ Event system
• ✅ Metadata support

📦 Installation

Requirements

• PHP 8.0+

Laravel compatibility

Setup

1. Install the package:

2. Publish and run migrations:

3. Publish config (optional):

   💡 The config file allows you to customize table name, model, fallback URLs, and more.

📖 Usage Guide

Banning Models

Make a Model Bannable

Add the Bannable trait to any model:

💡 You can add the trait to multiple models (User, Team, Group, etc.)

Basic Operations

Advanced Ban Options

⚠️ Without expired_at, the ban is permanent.

Query Scopes

List Bans

Banning IPs

Basic Operations

Unban IPs

Check & List Banned IPs

Country Blocking

Block access from specific countries automatically.

Configuration

1. Enable country blocking in config/ban.php:

2. Specify blocked countries:

That's it! The middleware will automatically block requests from these countries.

⚠️ Rate Limit Notice: The free version of ip-api.com has a limit of 45 requests/minute. Exceeding this will result in 429 errors until the limit resets.

💡 Want to improve this? If you have suggestions for better geolocation services or want to contribute improvements, please open an issue or submit a pull request.

Middleware

Protect your routes with ban middleware:

Available Middleware

Usage

💡 Tip: logout.banned includes the functionality of both auth.banned and ip.banned, so you don't need to use them together.

Scheduler

Banhammer automatically deletes expired bans using Laravel's scheduler.

Setup

⚠️ Important: You must have a cron job running Laravel's scheduler:

See: Laravel Scheduler Docs

Configuration

By default, the banhammer:unban command runs every minute. You can customize this:

Disable automatic scheduler:

Or via environment:

Change frequency:

Or via environment:

Available frequencies: everyMinute, everyFiveMinutes, everyTenMinutes, everyFifteenMinutes, everyThirtyMinutes, hourly, daily, twiceDaily, etc.

Events

Listen to ban/unban events:

🔧 Advanced Topics

Metas

Store additional data with bans:

Filter by Meta

Ban with Metas

UUIDs

To use UUIDs instead of auto-incrementing IDs:

1. Publish migrations:

2. Edit the migration:

3. Create a custom Ban model:

4. Update config:

Upgrading To 2.0 from 1.x

1. Update composer.json:

2. Update the package:

3. Update configuration:

🛠️ Development

Commands

Programmatic Usage

Testing

🤝 Contributing

We welcome contributions! Please:

• Open issues for bug reports or feature requests
• Submit pull requests (mark as "ready for review")
• Ensure all tests pass
• Follow Laravel coding standards

💡 Pull requests in "draft" state will be closed after a few days of inactivity.

🙏 Credits

Inspired by laravel-ban from cybercog.

📄 License

The MIT License (MIT). Please see License File for more information.