Banhammer

https://github.com/mchev/banhammer
Admin
A powerful Laravel package for banning Eloquent models, IP addresses, and entire countries with...
Tokens:54,479
Snippets:461
Trust Score:8.1
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### Install and Publish Banhammer Package

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Install the Banhammer package via Composer, publish its migrations, and run migrations to set up the database tables.

```bash
composer require mchev/banhammer
php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="migrations"
php artisan migrate
```

--------------------------------

### Install Banhammer via Composer

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Install the package using Composer. Requires PHP 8.0+ and Laravel 9.x or later.

```bash
composer require mchev/banhammer
```

--------------------------------

### Set, get, check, and remove ban meta

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Store additional data with bans using setMeta, getMeta, hasMeta, and forgetMeta methods.

```php
// Set meta
$ban->setMeta('username', 'Jane');
$ban->setMeta('reason', 'spam');

// Get meta
$ban->getMeta('username'); // 'Jane'

// Check if meta exists
$ban->hasMeta('username'); // true

// Remove meta
$ban->forgetMeta('username');
```

--------------------------------

### Run tests with composer

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Execute `composer test` to run the test suite.

```bash
composer test
```

--------------------------------

### Environment Variables Example (.env)

Source: https://github.com/mchev/banhammer

Example environment variable configuration for Banhammer. Set BANHAMMER_BLOCK_BY_COUNTRY to enable/disable country blocking, BANHAMMER_SCHEDULER_ENABLED to disable the automatic unban schedule, and BANHAMMER_SCHEDULER_PERIODICITY to override the scheduler frequency.

```env
BANHAMMER_BLOCK_BY_COUNTRY=false
BANHAMMER_SCHEDULER_ENABLED=false
BANHAMMER_SCHEDULER_PERIODICITY=hourly
```

--------------------------------

### Publish migrations for UUIDs

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Command to publish the package migrations so you can edit them for UUID support.

```bash
php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="migrations"
```

--------------------------------

### Publish and run migrations

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Publish the package migrations and run them to create the necessary database tables.

```bash
php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="migrations"
php artisan migrate
```

--------------------------------

### Meta CRUD usage example

Source: https://github.com/mchev/banhammer

Shows how to set, get, check, and forget meta keys on a Ban model. setMeta and forgetMeta only modify in-memory data until save() is called.

```php
use Mchev\Banhammer\Models\Ban;

$ban = Ban::find(1);

$ban->setMeta('username', 'Jane');        // in-memory only
$ban->setMeta('reason', 'spam');
$ban->save();                              // persist

$ban->getMeta('username');                 // 'Jane'
$ban->getMeta('missing', 'fallback');      // 'fallback'
$ban->hasMeta('reason');                   // true

$ban->forgetMeta('reason')->save();
```

--------------------------------

### Update Banhammer package

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Run composer update to install the new version.

```bash
composer update mchev/banhammer
```

--------------------------------

### Check and list banned IPs

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Check if an IP is banned, get all banned IPs as a collection, or as an array of IP strings.

```php
// Check if IP is banned
IP::isBanned("8.8.8.8"); // bool

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

--------------------------------

### Publish config file (optional)

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Publish the configuration file to customize table name, model, fallback URLs, and more.

```bash
php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="config"
```

--------------------------------

### Unban IP addresses

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Unban single or multiple IP addresses.

```php
// Unban single IP
IP::unban("8.8.8.8");

// Unban multiple IPs
IP::unban(["8.8.8.8", "4.4.4.4"]);
```

--------------------------------

### Scheduler setup in boot()

Source: https://github.com/mchev/banhammer

Schedules the 'banhammer:unban' command with the configured periodicity method. Falls back to 'everyMinute()' if the method does not exist on the schedule-event object.

```php
$this->app->booted(function () {
    $schedule = $this->app->make(Schedule::class);
    $periodicity = config('ban.scheduler_periodicity', 'everyMinute');

    $scheduledCommand = $schedule->command('banhammer:unban');

    if (method_exists($scheduledCommand, $periodicity)) {
        $scheduledCommand->{$periodicity}();
    } else {
        $scheduledCommand->everyMinute();
    }
});
```

--------------------------------

### Update configuration for Banhammer 2.0

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Backup your current config, republish the package config with --force, and review/merge custom settings.

```bash
# Backup your current config
cp config/ban.php config/ban.php.backup

# Republish config
php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="config" --force

# Review and merge any custom settings
```

--------------------------------

### Ban IP with expiration date

Source: https://github.com/mchev/banhammer/blob/2.x/CHANGELOG.md

Adds an expiration date when banning an IP. The example bans IP 8.8.8.8 with no metadata and an expiration 10 minutes from now.

```php
IP::ban("8.8.8.8", [], now()->addMinutes(10));
```

--------------------------------

### unban() usage example

Source: https://github.com/mchev/banhammer

Shows how to call unban on a user. All of the user's bans become soft-deleted.

```php
$user->unban();   // all of this user's bans become soft-deleted
```

--------------------------------

### List bans with expiration filters

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Retrieve all bans for a model, only expired bans, or active (not expired) bans.

```php
// All bans for a model
$bans = $user->bans()->get();

// Only expired bans
$expired = $user->bans()->expired()->get();

// Active bans
$active = $user->bans()->notExpired()->get();
```

--------------------------------

### Enable country blocking in config

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Enable country blocking by setting 'block_by_country' to true in config/ban.php.

```php
'block_by_country' => true,
```

--------------------------------

### Usage of Banhammer::unbanExpired()

Source: https://github.com/mchev/banhammer

Example usage to delete expired bans and invalidate IP cache.

```php
use Mchev\Banhammer\Banhammer;

// Delete all expired (non-permanent, past-due) bans and invalidate the IP cache
Banhammer::unbanExpired();
```

--------------------------------

### bannable() usage example

Source: https://github.com/mchev/banhammer

Shows how to access the bannable model through the relation. Returns null for IP bans.

```php
$ban = Ban::find(1);

// Access the banned model through the relation
$user = $ban->bannable;   // null when this ban is an IP ban
$user = $ban->bannable()->first();
```

--------------------------------

### Ban with metas

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Pass an array with a 'metas' key when banning a user or IP to store additional data like route and user agent.

```php
// When banning
$user->ban([
    'metas' => [
        'route' => request()->route()->getName(),
        'user_agent' => request()->header('user-agent')
    ]
]);

IP::ban("8.8.8.8", [
    'reason' => 'spam',
    'severity' => 'high'
]);
```

--------------------------------

### Cron job for Laravel scheduler

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Required cron entry to run Laravel's scheduler every minute. Replace the path with your project's location.

```bash
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
```

--------------------------------

### Query scopes usage examples

Source: https://github.com/mchev/banhammer

Shows how to use the query scopes: banned() for active bans, notBanned() and banned(false) for never-banned users, whereBansMeta() for specific meta, and bannedByType() for bans by an admin class.

```php
use App\Models\User;

// Active bans
$bannedUsers   = User::banned()->get();

// Users that have never been banned (two equivalent spellings)
$activeUsers   = User::notBanned()->get();
$activeUsers   = User::banned(false)->get();

// Users currently banned with a specific meta
$spammers = User::whereBansMeta('reason', 'spam')->get();

// Users banned by an admin
$moderated = User::bannedByType(\App\Models\Admin::class)->get();
```

--------------------------------

### IP::banned()

Source: https://github.com/mchev/banhammer

Static method to get a query builder for banned IPs.

```APIDOC
## IP::banned()

### Description
Static method to get a query builder for banned IPs.

### Method
banned

### Signature
`public static function banned(): Builder`

### Parameters
None

### Return Value
- **Builder** - A query builder instance for banned IPs.
```

--------------------------------

### Edit migration to use UUID

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Replace the auto-incrementing id with a UUID column in the published migration.

```diff
- $table->id();
+ $table->uuid('id');
```

--------------------------------

### Query scopes for banned and not banned

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Use query scopes to retrieve banned or non-banned users. The 'banned(false)' syntax is an alternative to 'notBanned()'.

```php
// Get banned users
$bannedUsers = User::banned()->get();

// Get non-banned users
$activeUsers = User::notBanned()->get();

// Alternative syntax
$activeUsers = User::banned(false)->get();
```

--------------------------------

### Filter bans by meta

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Query bans that have specific meta values using whereMeta on IP::banned(), $user->bans(), or User::whereBansMeta().

```php
// Find bans with specific meta
IP::banned()->whereMeta('username', 'Jane')->get();
$user->bans()->whereMeta('reason', 'spam')->get();
User::whereBansMeta('username', 'Jane')->get();
```

--------------------------------

### banUntil() usage examples

Source: https://github.com/mchev/banhammer

Shows how to call banUntil with a relative date string and an absolute date. The first uses a relative parse, the second an absolute date.

```php
$user->banUntil('2 days');     // relative parse
$user->banUntil('2025-01-01'); // absolute date
```

--------------------------------

### Apply ban middleware to routes

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Protect routes with ban middleware: 'auth.banned' for banned users, 'ip.banned' for banned IPs, and 'logout.banned' for both.

```php
// Single route
Route::get('/dashboard', [DashboardController::class, 'index'])
    ->middleware('auth.banned');

// Route group
Route::middleware(['auth.banned'])->group(function () {
    Route::get('/profile', [ProfileController::class, 'index']);
    Route::get('/settings', [SettingsController::class, 'index']);
});

// Block IPs on all routes
// Add to app/Http/Kernel.php:
protected $middleware = [
    // ...
    \Mchev\Banhammer\Middleware\IPBanned::class,
];
```

--------------------------------

### Update composer.json for Banhammer 2.0

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Change the required version of mchev/banhammer to ^2.0 in composer.json.

```json
"require": {
    "mchev/banhammer": "^2.0"
}
```

--------------------------------

### Listen to ban and unban events

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Register listeners for ModelWasBanned and ModelWasUnbanned events. The event object provides the ban and its bannable model.

```php
use Mchev\Banhammer\Events\ModelWasBanned;
use Mchev\Banhammer\Events\ModelWasUnbanned;

Event::listen(ModelWasBanned::class, function ($event) {
    // User was banned
    Log::info("User {$event->ban->bannable->id} was banned");
});

Event::listen(ModelWasUnbanned::class, function ($event) {
    // User was unbanned
    Log::info("User {$event->ban->bannable->id} was unbanned");
});
```

--------------------------------

### Ban a User

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Call the ban method on a model instance to ban it. This is the core action for banning a model.

```php
$user->ban();
```

--------------------------------

### createdBy() usage example

Source: https://github.com/mchev/banhammer

Shows how to access the entity that issued the ban. Returns null if no authenticated user.

```php
$ban = Ban::find(1);
$admin = $ban->createdBy;   // e.g. App\Models\Admin instance, or null
```

--------------------------------

### Ban IP addresses

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Ban single or multiple IP addresses, with optional expiration and metadata.

```php
use Mchev\Banhammer\IP;

// Ban single IP
IP::ban("8.8.8.8");

// Ban multiple IPs
IP::ban(["8.8.8.8", "4.4.4.4", "1.1.1.1"]);

// Ban with expiration
IP::ban("8.8.8.8", [], now()->addMinutes(10));

// Ban with metadata
IP::ban("8.8.8.8", [
    'reason' => 'spam',
    'severity' => 'high'
]);
```

--------------------------------

### Change scheduler frequency via environment

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Set BANHAMMER_SCHEDULER_PERIODICITY in your environment to change the frequency.

```env
BANHAMMER_SCHEDULER_PERIODICITY=everyFiveMinutes
```

--------------------------------

### IP::unban() usage example

Source: https://github.com/mchev/banhammer

Unbans one or multiple IPs. Repeated calls are safe; already-unbanned IPs match zero rows.

```php
use Mchev\Banhammer\IP;

IP::unban("8.8.8.8");          // unban one IP
IP::unban(["8.8.8.8", "4.4.4.4"]); // unban several IPs

// Unbanning multiple times is safe; already-unbanned IPs simply match zero rows
IP::unban("8.8.8.8");
```

--------------------------------

### Specify blocked countries in config

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Define the list of country codes to block. The middleware will automatically block requests from these countries.

```php
'blocked_countries' => ['FR', 'ES', 'US'],
```

--------------------------------

### Event listeners for ModelWasBanned and ModelWasUnbanned

Source: https://github.com/mchev/banhammer

Example listeners reacting to the events dispatched by the observer. The ModelWasUnbanned event provides the MorphTo relation; resolve with ->getResults().

```php
use Mchev\Banhammer\Events\ModelWasBanned;
use Mchev\Banhammer\Events\ModelWasUnbanned;
use Illuminate\Support\Facades\Event;

// The observer dispatches these; react in your own listeners
Event::listen(ModelWasBanned::class, function ($event) {
    // $event->ban->bannable->id, $event->ban->ip, $event->ban->metas, ...
});

Event::listen(ModelWasUnbanned::class, function ($event) {
    // $event->model is the MorphTo relation; resolve with ->getResults()
});
```

--------------------------------

### Basic ban operations

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Perform basic ban operations on a model instance: ban, ban with expiration, check status, and unban.

```php
$user->ban()
```

```php
$user->banUntil('2 days')
```

```php
$user->isBanned()
```

```php
$user->isNotBanned()
```

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

--------------------------------

### Verifying the session side-effect

Source: https://github.com/mchev/banhammer

Example showing how to ban an IP and a user, then describes the expected behavior on the next request from a banned user: logout, session invalidation, CSRF token regeneration, and throwing BanhammerException with config('ban.messages.user').

```php
use Mchev\Banhammer\IP;

IP::ban('203.0.113.5');
$user->ban(); // bans the authenticated user

// Next request from a banned user:
// 1. auth()->logout()  — session user cleared
// 2. session invalidated + CSRF token regenerated
// 3. BanhammerException(config('ban.messages.user')) thrown -> 403 / redirect
```

--------------------------------

### Delete expired bans via artisan command

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Run `php artisan banhammer:unban` to manually delete expired bans.

```bash
# Manually delete expired bans
php artisan banhammer:unban
```

--------------------------------

### Create custom Ban model with UUIDs

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Extend the package's Ban model and use the HasUuids trait to enable UUID primary keys.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Mchev\Banhammer\Models\Ban as BanhammerBan;

class Ban extends BanhammerBan
{
    use HasUuids;
}
```

--------------------------------

### Update config to use custom Ban model

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Set the 'model' config option to your custom Ban model class.

```php
// config/ban.php
'model' => \App\Models\Ban::class,
```

--------------------------------

### Permanently delete all expired bans via artisan command

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Run `php artisan banhammer:clear` to permanently delete all expired bans.

```bash
# Permanently delete all expired bans
php artisan banhammer:clear
```

--------------------------------

### Advanced ban options

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Ban a user with additional options like comment, IP, expiration, creator info, and metadata. Without 'expired_at', the ban is permanent.

```php
$user->ban([
    'comment' => "You've been evil",
    'ip' => "8.8.8.8",
    'expired_at' => Carbon::now()->addDays(7),
    'created_by_type' => 'App\Models\Admin',
    'created_by_id' => auth()->id(),
    'metas' => [
        'route' => request()->route()->getName(),
        'user_agent' => request()->header('user-agent')
    ]
]);
```

--------------------------------

### Listening to ModelWasUnbanned with incorrect $event->ban access

Source: https://github.com/mchev/banhammer

Example from README that attempts to access $event->ban, which is undefined on this event. The event only carries $model, so this snippet fails as noted.

```php
use Mchev\Banhammer\Events\ModelWasUnbanned;
use Illuminate\Support\Facades\Event;

Event::listen(ModelWasUnbanned::class, function ($event) {
    // README example — note: ModelWasUnbanned carries NO $ban property,
    // so accessing $event->ban (as the README's own snippet would) fails.
    Log::info("User {$event->ban->bannable->id} was unbanned"); // ⚠️ $event->ban undefined
});
```

--------------------------------

### IP::banned() usage example

Source: https://github.com/mchev/banhammer

Retrieves active IP-ban rows, a flat array of unique banned IPs, or a count of distinct banned IPs.

```php
use Mchev\Banhammer\IP;

// All currently active IP-ban rows (models, with createdBy loaded)
$ipBans = IP::banned()->get();

// Flat array of unique banned IPs
$ips = IP::banned()->pluck('ip')->unique()->toArray();

// Count of distinct banned IPs
$count = IP::banned()->distinct()->count('ip');
```

--------------------------------

### boot() method signature

Source: https://github.com/mchev/banhammer

Declares the boot method that runs on every request/console boot. It registers the observer, middleware aliases, country blocking, console publishing, and scheduler.

```php
public function boot(): void
```

--------------------------------

### IP::isBanned() usage example

Source: https://github.com/mchev/banhammer

Checks if the current request IP is banned, allowing custom rejection outside the middleware layer.

```php
use Mchev\Banhammer\IP;

if (IP::isBanned($request->ip())) {
    // Reject request outside the middleware layer
}
```

--------------------------------

### creating($ban) method

Source: https://github.com/mchev/banhammer

Fills audit columns (created_by_type and created_by_id) from the authenticated user when they are null and a user is logged in. Fires before the DB insert.

```php
public function creating($ban): void
{
    $user = auth()->user();
    if ($user && is_null($ban->created_by_type) && is_null($ban->created_by_id)) {
        $ban->fill([
            'created_by_type' => $user->getMorphClass(),
            'created_by_id' => $user->getKey(),
        ]);
    }
}
```

--------------------------------

### IpApiService::getGeolocationData()

Source: https://github.com/mchev/banhammer

Service method to get geolocation data for an IP address.

```APIDOC
## IpApiService::getGeolocationData()

### Description
Service method to get geolocation data for an IP address.

### Method
getGeolocationData

### Signature
`public function getGeolocationData(string $ip): ?array`

### Parameters
- **ip** (string) - Required - The IP address to look up.

### Return Value
- **?array** - An array of geolocation data or null if not found.
```

--------------------------------

### Defensive handling of nullable return from getGeolocationData

Source: https://github.com/mchev/banhammer

Shows how to handle the nullable return value. If null, the request fails open; if status is 'fail', the lookup was rejected. Logs warnings and notices accordingly.

```php
use Mchev\Banhammer\Services\IpApiService;
use Illuminate\Support\Facades\Log;

$data = app(IpApiService::class)->getGeolocationData($request->ip());

if ($data === null) {
    // HTTP failure — logged inside the service as 'IP-API Service Error: ...'
    Log::warning('Geolocation unavailable, allowing request');
    return; // fail-open
}

if (($data['status'] ?? '') === 'fail') {
    // ip-api.com rejected the query (reserved IP, rate limit, ...)
    Log::notice("Lookup failed: {$data['message']}");
} else {
    $country = $data['countryCode'] ?? '??';
    // country-based decision
}
```

--------------------------------

### Catching BanhammerException in application code

Source: https://github.com/mchev/banhammer

Example of catching BanhammerException in application code. The exception's getStatusCode() returns 403 and getMessage() returns the configured ban message. Calling report($e) triggers the report() method which logs the error.

```php
use Mchev\Banhammer\Exceptions\BanhammerException;

try {
    $response = app('router')->dispatch($request);
} catch (BanhammerException $e) {
    // $e->getStatusCode() === 403
    // $e->getMessage()    === config('ban.messages.user'|'ip'|'country')
    report($e); // triggers ->report(): Log::error("Banhammer Exception: ...")
}
```

--------------------------------

### Publishing migrations and config

Source: https://github.com/mchev/banhammer

Artisan commands to publish the package's migrations (required) and config (optional) using the provider and tags.

```bash
# Migrations (required)
php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="migrations"

# Config (optional)
php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="config"
```

--------------------------------

### Import BanObserver class

Source: https://github.com/mchev/banhammer

Import path for the BanObserver class. The observer is attached to the configured ban model by the service provider and should not be registered manually.

```php
use Mchev\Banhammer\Observers\BanObserver;
```

--------------------------------

### Disable automatic scheduler via environment

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Set BANHAMMER_SCHEDULER_ENABLED=false in your environment to disable the scheduler.

```env
BANHAMMER_SCHEDULER_ENABLED=false
```

--------------------------------

### Import Mchev\Banhammer\IP

Source: https://github.com/mchev/banhammer

Import the static helper class for banning, unbanning, and querying IP addresses. All members are public static and the class is never instantiated.

```php
use Mchev\Banhammer\IP;
```

--------------------------------

### Basic usage of getGeolocationData

Source: https://github.com/mchev/banhammer

Demonstrates a basic call to getGeolocationData with a public IP. The expected result is an array with 'status', 'countryCode', and 'query' keys.

```php
use Mchev\Banhammer\Services\IpApiService;

$service = app(IpApiService::class);
$data = $service->getGeolocationData('8.8.8.8');

// $data ≈ ['status' => 'success', 'countryCode' => 'US', 'query' => '8.8.8.8']
```

--------------------------------

### Error handling and cache warming

Source: https://github.com/mchev/banhammer

Observe non-ban exceptions in logs and pre-warm the banned-ips cache to avoid DB hits on first request.

```php
// The catch-and-rethrow path also surfaces non-ban exceptions; observe them in the logs:
// [error] IPBanned Middleware Exception: <message> {"exception":{...}}

// Cache-warm ahead of traffic spikes so the first request doesn't hit the DB:
use Mchev\Banhammer\IP;
use Illuminate\Support\Facades\Cache;

Cache::remember('banned-ips', now()->addMinutes(5), fn () => IP::banned()->pluck('ip')->unique()->toArray());
```

--------------------------------

### Delete expired bans programmatically

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Use `Banhammer::unbanExpired()` to delete expired bans in PHP code.

```php
use Mchev\Banhammer\Banhammer;

// Delete expired bans
Banhammer::unbanExpired();
```

--------------------------------

### handle() method implementation

Source: https://github.com/mchev/banhammer

Full implementation of the handle() method. It checks the client IP against a configured list of blocked countries, using a cache to store verdicts. Throws BanhammerException when the country is blocked. On API failure, it logs a notice and caches 'allowed'. On exceptions, it logs debug and throws.

```php
public function handle(Request $request, Closure $next)
{
    $blockedCountries = config('ban.blocked_countries');

    if ($blockedCountries && ! empty($blockedCountries)) {
        $ip = $request->ip();

        if (! is_null($ip)) {
            $cacheKey = 'banhammer_'.$ip;
            $cachedResult = Cache::get($cacheKey);

            if ($cachedResult === null) {
                try {
                    $geolocationData = $this->ipApiService->getGeolocationData($ip);

                    if ($geolocationData['status'] === 'fail') {
                        Log::notice('Banhammer country check failure: '.$geolocationData['message'], [
                            'ip' => $ip,
                        ]);
                        Cache::put($cacheKey, 'allowed', now()->addMinutes(config('ban.cache_duration')));
                    } else {
                        if (in_array($geolocationData['countryCode'], $blockedCountries)) {
                            Cache::put($cacheKey, 'blocked', now()->addMinutes(config('ban.cache_duration')));
                            throw new BanhammerException(config('ban.messages.country'));
                        }
                    }

                } catch (\Exception $e) {
                    Log::debug('Banhammer Exception: '.$e->getMessage(), [
                        'ip' => $ip,
                        'country' => $geolocationData['countryCode'] ?? null,
                    ]);
                    throw new BanhammerException(config('ban.messages.country'));
                }
            } elseif ($cachedResult === 'blocked') {
                throw new BanhammerException(config('ban.messages.country'));
            }
        }
    }

    return $next($request);
}
```

--------------------------------

### handle() method implementation

Source: https://github.com/mchev/banhammer

Implementation of handle() that checks the request IP against the cached banned list, throws and rethrows exceptions, and passes the request to the next middleware.

```php
public function handle($request, Closure $next): Response
{
    try {
        $bannedIPs = $this->getBannedIPsFromCache();

        if ($request->ip() && in_array($request->ip(), $bannedIPs)) {
            throw new BanhammerException(config('ban.messages.ip'));
        }
    } catch (\Exception $e) {
        // Log the exception
        Log::error('IPBanned Middleware Exception: '.$e->getMessage(), ['exception' => $e]);

        throw $e;
    }

    return $next($request);
}
```

--------------------------------

### Merging configuration in register()

Source: https://github.com/mchev/banhammer

Merges the package configuration file into the application's config repository under the 'ban' key.

```php
$this->mergeConfigFrom(__DIR__.'/../config/config.php', 'ban');
```

--------------------------------

### Add Bannable Trait to Model

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Use the Bannable trait in an Eloquent model to enable banning functionality for that model.

```php
use Mchev\Banhammer\Traits\Bannable;

class User extends Model
{
    use Bannable;
}
```

--------------------------------

### Import IPBanned middleware

Source: https://github.com/mchev/banhammer

Import the IPBanned middleware class for use in route or global middleware registration.

```php
use Mchev\Banhammer\Middleware\IPBanned;
```

--------------------------------

### Permanently delete expired bans programmatically

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Use `Banhammer::clear()` to permanently delete expired bans in PHP code.

```php
use Mchev\Banhammer\Banhammer;

// Permanently delete expired bans
Banhammer::clear();
```

--------------------------------

### Disable automatic scheduler via config

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Set 'scheduler_enabled' to false in config/ban.php to disable the automatic 'banhammer:unban' command.

```php
// config/ban.php
'scheduler_enabled' => false,
```

--------------------------------

### Constructor

Source: https://github.com/mchev/banhammer

Creates a new BanhammerException instance with a hard-coded HTTP 403 status. Accepts an optional message, previous exception, and code.

```APIDOC
## Constructor

### Description
Creates a new BanhammerException instance with a hard-coded HTTP 403 status. Accepts an optional message, previous exception, and code.

### Signature
```php
public function __construct($message = null, ?Exception $previous = null, $code = 0)
```

### Parameters
- **$message** (string|null) - Optional - Human-readable ban reason (middleware passes `config('ban.messages.*')`)
- **$previous** (?Exception) - Optional - Previous exception for chaining
- **$code** (int) - Optional - Passed through to the underlying `HttpException`

### Behavior
Constructing the exception does not throw; the middleware `throw new BanhammerException(...)` in request context. The status code property is always `403`, regardless of `$code`.
```

--------------------------------

### Import Banhammer class

Source: https://github.com/mchev/banhammer

Import the Banhammer facade class for use in PHP code.

```php
use Mchev\Banhammer\Banhammer;
```

--------------------------------

### Resolve IpApiService from Laravel container

Source: https://github.com/mchev/banhammer

Shows how to obtain an instance of IpApiService via the Laravel service container. The class has no constructor, so it can be instantiated without arguments.

```php
use Mchev\Banhammer\Services\IpApiService;

$service = app(IpApiService::class);
```

--------------------------------

### handle() method signature

Source: https://github.com/mchev/banhammer

Signature of the handle() method in the BlockByCountry middleware. It accepts the injected Request and the next middleware Closure.

```php
public function handle(Request $request, Closure $next)
```

--------------------------------

### register() method signature

Source: https://github.com/mchev/banhammer

Declares the register method that merges the package configuration so 'config('ban.*')' is available without publishing.

```php
public function register()
```

--------------------------------

### Import AuthBanned middleware

Source: https://github.com/mchev/banhammer

Import the AuthBanned middleware class for use in PHP files.

```php
use Mchev\Banhammer\Middleware\AuthBanned;
```

--------------------------------

### ban() basic usage

Source: https://github.com/mchev/banhammer

Shows how to create a permanent ban with no attributes, and a ban with a comment and custom expiry using now()->addDays(7).

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

// Permanent ban
$ban = $user->ban();

// Ban with a comment and custom expiry
$user->ban([
    'comment' => "You've been evil",
    'expired_at' => now()->addDays(7),
]);
```

--------------------------------

### Usage of IP::getBannedIPsFromCache()

Source: https://github.com/mchev/banhammer

Shows how to retrieve the list of banned IPs and check if the current request IP is banned, aborting with a 403 if so.

```php
use Mchev\Banhammer\IP;

$bannedIPs = IP::getBannedIPsFromCache();

if (in_array($request->ip(), $bannedIPs)) {
    abort(403);
}
```

--------------------------------

### Basic usage: ban an IP and protect a route

Source: https://github.com/mchev/banhammer

Ban an IP with IP::ban() and then protect a route with the 'ip.banned' middleware.

```php
use Mchev\Banhammer\IP;

// Ban an IP…
IP::ban('203.0.113.9');

// …then any request from that IP hits the middleware
Route::get('/restricted', fn () => 'secret')->middleware('ip.banned');
```

--------------------------------

### render()

Source: https://github.com/mchev/banhammer

Renders the exception response. Redirects to the configured fallback URL if set, otherwise aborts with a 403 status and the exception message.

```APIDOC
## render()

### Description
Renders the exception response. Redirects to the configured fallback URL if set, otherwise aborts with a 403 status and the exception message.

### Signature
```php
public function render(Request $request): Response|RedirectResponse
```

### Parameters
- **$request** (Illuminate\Http\Request) - Required - The request that triggered the ban

### Return
`Illuminate\Http\Response|Illuminate\Http\RedirectResponse` - A redirect to `config('ban.fallback_url')` when configured (and truthy), otherwise a 403 abort whose body carries `config('ban.messages.*')`.

### Behavior
The fallback check is a truthiness test: `null`, `''`, and `0` all fall back to the 403 `abort()`. A URL **must** be non-empty and the render path only runs if your app's exception handler lets this exception reach `render()` — middleware that both throws and catches (`IPBanned`) rethrows after logging, so it still reaches Laravel's handler.

### Example
```php
return (config('ban.fallback_url'))
    ? redirect(config('ban.fallback_url'))
    : abort(403, $this->getMessage());
```
```

--------------------------------

### BlockByCountry Constructor

Source: https://github.com/mchev/banhammer

Constructor for the BlockByCountry middleware. It receives an IpApiService instance via dependency injection, which is used to resolve the country for an IP address.

```php
public function __construct(protected IpApiService $ipApiService)
```

--------------------------------

### BanhammerException render() implementation

Source: https://github.com/mchev/banhammer

Redirects to config('ban.fallback_url') when configured and truthy, otherwise aborts with a 403 status and the ban message. The fallback check is a truthiness test: null, '', and 0 all fall back to the 403 abort.

```php
return (config('ban.fallback_url'))
    ? redirect(config('ban.fallback_url'))
    : abort(403, $this->getMessage());
```

--------------------------------

### created($ban) method

Source: https://github.com/mchev/banhammer

Dispatches the ModelWasBanned event with the bannable relation and the ban, then invalidates IP caches. The event is queued by default.

```php
public function created($ban): void
{
    event(new ModelWasBanned($ban->bannable(), $ban));
    $this->updateCachedIps($ban);
}
```

--------------------------------

### Change scheduler frequency via config

Source: https://github.com/mchev/banhammer/blob/2.x/README.md

Set 'scheduler_periodicity' in config/ban.php to change how often the unban command runs. Available values include everyMinute, everyFiveMinutes, hourly, daily, etc.

```php
// config/ban.php
'scheduler_periodicity' => 'everyFiveMinutes', // or 'hourly', 'daily', etc.
```

--------------------------------

### getGeolocationData() implementation with caching and error handling

Source: https://github.com/mchev/banhammer

Full implementation of getGeolocationData. It caches the response for one day under 'ip_geolocation_{ip}', logs any exception as 'IP-API Service Error: ...', and returns null on failure without re-throwing.

```php
public function getGeolocationData(string $ip): ?array
{
    // Cache key for storing geolocation data
    $cacheKey = 'ip_geolocation_'.$ip;

    try {
        // Try to retrieve geolocation data from cache
        $geolocationData = Cache::remember($cacheKey, now()->addDay(), function () use ($ip) {
            $response = Http::get("http://ip-api.com/json/{$ip}?fields=status,message,countryCode,query");

            return $response->json();
        });

        return $geolocationData;
    } catch (\Exception $e) {
        // Log the error
        Log::error('IP-API Service Error: '.$e->getMessage(), ['exception' => $e]);

        // Handle the error as needed
        return null;
    }
}
```

--------------------------------

### Custom error handling via exception handler

Source: https://github.com/mchev/banhammer

Example of registering a custom renderable callback in app/Exceptions/Handler.php to return a JSON response for BanhammerException. The callback receives the exception and request, and returns a 403 JSON response with the ban message.

```php
// app/Exceptions/Handler.php
use Mchev\Banhammer\Exceptions\BanhammerException;

public function register(): void
{
    $this->renderable(function (BanhammerException $e, $request) {
        return response()->json([
            'error' => 'banned',
            'message' => $e->getMessage(),
        ], 403);
    });
}
```

--------------------------------

### ban() full attribute set usage

Source: https://github.com/mchev/banhammer

Demonstrates passing all supported attributes: comment, ip, expired_at (as Carbon), created_by_type/id, and metas. Requires importing Bannable trait and Carbon.

```php
use Mchev\Banhammer\Traits\Bannable;
use Illuminate\Support\Carbon;

$user->ban([
    'comment' => "You've been evil",
    'ip' => '8.8.8.8',
    'expired_at' => Carbon::now()->addDays(7),
    'created_by_type' => 'App\Models\Admin',
    'created_by_id' => auth()->id(),
    'metas' => [
        'route' => request()->route()?->getName(),
        'user_agent' => request()->header('user-agent'),
    ],
]);
```

--------------------------------

### handle() method signature

Source: https://github.com/mchev/banhammer

Signature of the handle method that processes the request.

```php
public function handle($request, Closure $next): Response
```

--------------------------------

### handle() method implementation

Source: https://github.com/mchev/banhammer

Implementation that throws BanhammerException if the authenticated user is banned, otherwise passes to the next middleware.

```php
public function handle($request, Closure $next): Response
{
    if ($request->user() && $request->user()->isBanned()) {
        throw new BanhammerException(config('ban.messages.user'));
    }

    return $next($request);
}
```

--------------------------------

### getGeolocationData() method signature

Source: https://github.com/mchev/banhammer

Declares the public method getGeolocationData that accepts an IP string and returns an array or null. It is the main entry point for geolocation lookups.

```php
public function getGeolocationData(string $ip): ?array
```

--------------------------------

### Import BanhammerException

Source: https://github.com/mchev/banhammer

Import the custom exception class from the package namespace.

```php
use Mchev\Banhammer\Exceptions\BanhammerException;
```

--------------------------------

### IP::ban() implementation

Source: https://github.com/mchev/banhammer

Implementation of the ban method. For each IP, it checks for an existing non-expired ban and skips if found; otherwise creates a row with ip, metas (null if empty), and expired_at set to the provided date.

```php
public static function ban(string|array $ips, array $metas = [], ?string $date = null): void
{
    foreach ((array) $ips as $ip) {
        // Check if IP is already banned and not expired by querying database directly
        $existingBan = config('ban.model')::where('ip', $ip)
            ->notExpired()
            ->first();

        if (! $existingBan) {
            config('ban.model')::create([
                'ip' => $ip,
                'metas' => count($metas) ? $metas : null,
                'expired_at' => $date,
            ]);
        }
    }
}
```

--------------------------------

### Import LogoutBanned middleware

Source: https://github.com/mchev/banhammer

Import the LogoutBanned middleware class for use in your application.

```php
use Mchev\Banhammer\Middleware\LogoutBanned;
```

--------------------------------

### Artisan commands

Source: https://github.com/mchev/banhammer

Artisan commands provided by the package.

```APIDOC
## Artisan commands

### Description
Artisan commands provided by the package.

### Commands
- **banhammer:clear** - Clears all bans.
- **banhammer:unban** - Deletes expired bans.
```

--------------------------------

### createdBy() method signature

Source: https://github.com/mchev/banhammer

Declares the createdBy() relationship method returning a MorphTo relation. No parameters.

```php
public function createdBy(): MorphTo
```

--------------------------------

### getMeta method signature

Source: https://github.com/mchev/banhammer

Retrieves a meta value with an optional default, using Arr::get. Supports dot notation.

```php
public function getMeta(string $propertyName, $default = null): mixed
```

--------------------------------

### Register renderable callback for JSON APIs

Source: https://github.com/mchev/banhammer

Add a renderable callback in app/Exceptions/Handler.php to return a JSON response for BanhammerException. This is useful for JSON APIs to customize the error format.

```php
// app/Exceptions/Handler.php
$this->renderable(function (BanhammerException $e, $request) {
    return response()->json(['error' => 'banned', 'message' => $e->getMessage()], 403);
});
```

--------------------------------

### Basic usage: listen to ModelWasBanned

Source: https://github.com/mchev/banhammer

Registers a listener that logs the banned user's ID. The README pattern resolves the model through $event->ban->bannable, not $event->model.

```php
use Mchev\Banhammer\Events\ModelWasBanned;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;

Event::listen(ModelWasBanned::class, function (ModelWasBanned $event) {
    // README pattern: resolve the model through the ban
    Log::info("User {$event->ban->bannable->id} was banned");
});
```

--------------------------------

### Customize ban message and fallback URL

Source: https://github.com/mchev/banhammer

Configure the ban message and fallback URL in config/ban.php. The exception renders redirect to fallback_url if set, otherwise abort(403).

```php
// The middleware reads the blocking message from config; customize per environment:
// config/ban.php
'messages' => [
    'user' => 'Your account has been banned.',
],

// The exception is rendered by BanhammerException::render():
//   - with a fallback_url set  -> redirect(config('ban.fallback_url'))
//   - without                  -> abort(403, 'Your account has been banned.')

'fallback_url' => '/login',
```

--------------------------------

### Basic configuration for block_by_country

Source: https://github.com/mchev/banhammer

Configure country blocking in config/ban.php. Middleware is auto-pushed to the 'web' group by the service provider. First request per IP performs the ip-api.com lookup; subsequent requests reuse the cached verdict for cache_duration minutes.

```php
// config/ban.php
'block_by_country' => true,
'blocked_countries' => ['FR', 'ES', 'US'],
'cache_duration' => 120,

// Middleware is auto-pushed to the 'web' group by the service provider.
// First request per IP performs the ip-api.com lookup; subsequent requests
// reuse the cached 'blocked' / 'allowed' verdict for cache_duration minutes.
```

--------------------------------

### Import paths for ModelWasBanned and ModelWasUnbanned

Source: https://github.com/mchev/banhammer

Import the two Laravel events dispatched by BanObserver when a ban row is created or deleted. Both implement ShouldQueue and are queued by default.

```php
use Mchev\Banhammer\Events\ModelWasBanned;
use Mchev\Banhammer\Events\ModelWasUnbanned;
```

--------------------------------

### Catch BanhammerException in try-catch block

Source: https://github.com/mchev/banhammer

Wrap operations that run the middleware chain (e.g., matching a route or an HTTP test caller) in a try-catch to handle BanhammerException. The exception provides getStatusCode() (403), getMessage() (from config('ban.messages.user'|'ip'|'country')), and getPrevious() (non-null only in the IPBanned rethrow path).

```php
use Mchev\Banhammer\Exceptions\BanhammerException;

try {
    // ... some operation that runs the middleware chain, e.g.:
    $response = app('router')->getRoutes()->match($request); // or an HTTP test caller
} catch (BanhammerException $e) {
    // $e->getStatusCode()              === 403
    // $e->getMessage()                 === config('ban.messages.user'|'ip'|'country')
    // $e->getPrevious()                !== null  (only in the IPBanned rethrow path)
    logger()->error('Ban blocked', ['ip' => $request->ip(), 'message' => $e->getMessage()]);
}
```

--------------------------------

### IP::ban() method signature

Source: https://github.com/mchev/banhammer

Signature for banning one IP or a list of IPs. Accepts a string or array of IPs, optional metadata, and an optional expiration date. Returns void.

```php
public static function ban(string|array $ips, array $metas = [], ?string $date = null): void
```
Tokens:
Raw