### Install HoneypotPlus Package

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Commands.md

Use this command to install the HoneypotPlus package, which publishes configuration files and database migrations. It prompts to run migrations immediately after installation.

```bash
php artisan honeypot-plus:install
```

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

### Example Usage of HoneypotPlus Facade

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Facades.md

A comprehensive example demonstrating various uses of the HoneypotPlus facade, including checking ban status, manually banning IPs, retrieving ban records, unbanning IPs, and fetching statistics.

```php
use HoneypotPlus\Facades\HoneypotPlus;

// Check if an IP is banned
if (HoneypotPlus::isBanned($requestIp)) {
    return response('Forbidden', 403);
}

// Ban an IP manually
HoneypotPlus::ban('203.0.113.42', 72); // Ban for 3 days

// Check ban status and get details
$record = HoneypotPlus::getBannedRecord('203.0.113.42');
if ($record) {
    echo "Banned: {$record->created_at}";
    echo "Expires: {$record->expiration_at->diffForHumans()}";
}

// Unban an IP
HoneypotPlus::unban('203.0.113.42');

// Get statistics for a dashboard
$stats = HoneypotPlus::getStats();
echo "Active bans: {$stats['active']}";
echo "Total attacks: {$stats['total']}";
```

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

### Run Honeypot Plus Installation Artisan Command

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/README.md

Execute this Artisan command after installing the package to publish configuration and migration files. This sets up the necessary files for the honeypot to function.

```bash
php artisan honeypot-plus:install
```

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

### Install and Configure Laravel HoneypotPlus

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Commands to install the package, publish its configuration, run migrations, and clear the config cache for production deployment.

```bash
# 1. Install package
composer install

# 2. Publish config (if not already)
php artisan vendor:publish --tag=honeypot-plus:config

# 3. Run migrations
php artisan migrate

# 4. Clear config cache
php artisan config:clear

# 5. Verify setup
php artisan about | grep HoneypotPlus
```

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

### Example HoneypotAttackDetected Event Data with Regex

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Events.md

Shows an example of the HoneypotAttackDetected event data when a regex pattern is matched, highlighting the 'regex:' prefix in the honeypotRule.

```php
HoneypotAttackDetected {
    ip: "198.51.100.15"
    honeypotRule: "regex:/wp-config\.php$/i"
    userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
    httpMethod: "GET"
    pathRequested: "/wp-config.php"
}
```

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

### Run Database Migrations

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Execute migrations to create the necessary database table for storing honeypot attacks if not run during installation.

```bash
php artisan migrate
```

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

### Install HoneypotPlus Package

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/00-START-HERE.md

Use this Artisan command to install the HoneypotPlus package into your Laravel application.

```bash
php artisan honeypot-plus:install     # Install package
```

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

### Show Statistics Example Output

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Commands.md

Presents a table of aggregate statistics for the honeypot, including total attacks, currently blocked IPs, expired bans, and reported IPs.

```bash
Statistics

┌─────────────────────┬───────┐
│ Metric              │ Count │
├─────────────────────┼───────┤
│ Total Attacks       │  127  │
│ Currently Blocked   │   5   │
│ Expired Bans        │  122  │
│ Reported to AbuseIPDB│  45  │
└─────────────────────┴───────┘
```

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

### Honeypot Commands

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/MANIFEST.txt

Artisan commands for installing, managing, and cleaning up the honeypot system.

```APIDOC
## Honeypot Commands

### Description
Provides Artisan commands for managing the Laravel HoneypotPlus package.

### Commands

- **honeypot-plus:install**
  Performs the initial setup and configuration for the package.

- **honeypot-plus:manage**
  An interactive command for managing honeypot settings and bans.

- **honeypot-plus:cleanup**
  Removes expired ban records from the database. Supports `--dry-run` and `--force` options.
```

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

### Import and Use HoneypotPlus Facade

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Facades.md

Import the HoneypotPlus facade and use its static methods to interact with the honeypot service. This example shows how to ban an IP and check if an IP is banned.

```php
use HoneypotPlus\Facades\HoneypotPlus;

HoneypotPlus::ban('192.168.1.1', 24);
HoneypotPlus::isBanned('192.168.1.1');
```

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

### Configure Queue Connection and Redis Queue

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Configure the queue connection and Redis queue name in your .env file. This example sets the connection to Redis and the queue name to 'default'.

```bash
QUEUE_CONNECTION=redis
REDIS_QUEUE=default
```

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

### Dry Run Example with Unban Preview

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Commands.md

Shows the output of the --dry-run option when expired bans are found, listing the IPs that would be unbanned without making changes.

```bash
$ php artisan honeypot-plus:cleanup --dry-run
Found 3 expired ban(s).

Would unban IP: 192.168.1.1
Would unban IP: 203.0.113.22
Would unban IP: 198.51.100.5

✓ Cleanup complete!
```

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

### HoneypotPlus CLI Commands

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/MANIFEST.txt

Artisan commands for package management and maintenance. Includes installation, interactive management, and cleanup tasks.

```php
honeypot-plus:install: Package setup
honeypot-plus:manage: Interactive management
honeypot-plus:cleanup: Expire old bans (options: --dry-run, --force)
```

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

### Cloudflare API Request Example

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Jobs.md

An example of the JSON payload sent to Cloudflare's Access Rules API to block an IP address. This is used within the BanViaCloudflare job.

```json
{
    "mode": "block",
    "configuration": {
        "target": "ip",
        "value": "192.168.1.1"
    },
    "notes": "[Laravel HoneypotPlus] Banned IP via honeypot-probe"
}
```

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

### HoneypotPlus Facade Usage Examples

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/types.md

Demonstrates how to use the HoneypotPlus facade to check if an IP address is banned and to retrieve general statistics. Ensure the facade is correctly resolved by the service container.

```php
use HoneypotPlus\Facades\HoneypotPlus;

HoneypotPlus::isBanned('192.168.1.1');
HoneypotPlus::getStats();
```

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

### Dry Run Example with Table Output

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Commands.md

Demonstrates the output of the --dry-run option when expired bans are found, showing a table of affected records and prompting for confirmation.

```bash
$ php artisan honeypot-plus:cleanup --dry-run
Found 3 expired ban(s).

┌────┬──────────────┬─────────────────────────┬──────────────┐
│ ID │ IP           │ Expired At              │ CF Rule ID   │
├────┼──────────────┼─────────────────────────┼──────────────┤
│ 1  │ 192.168.1.1  │ 2024-12-20 10:30:00     │ abc123def456 │
│ 2  │ 203.0.113.22 │ 2024-12-19 15:45:00     │ xyz789uvw012 │
│ 3  │ 198.51.100.5 │ 2024-12-18 08:00:00     │ null         │
└────┴──────────────┴─────────────────────────┴──────────────┘

Proceed with cleanup? (yes/no) [yes]: no
Cancelled.
```

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

### Get HoneypotPlus Statistics using Facade

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/types.md

Demonstrates how to retrieve honeypot statistics using the HoneypotPlus facade. This is a common way to access service functionalities statically.

```php
use HoneypotPlus\Facades\HoneypotPlus;

$stats = HoneypotPlus::getStats();
// Returns: ['total' => 127, 'active' => 5, 'expired' => 122, 'reported' => 45]
```

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

### Install Package via Composer

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Use Composer to add the Laravel HoneypotPlus package to your project dependencies.

```bash
composer require ilogus/laravel-honeypotplus
```

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

### Example Manual Ban Record

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/database-schema.md

This record illustrates a manually initiated ban, distinguished by a 'MANUAL' HTTP method and specific ban details.

```yaml
id: 2
ip: 192.168.1.100
honeypot_rule: manual-ban
user_agent: null
http_method: MANUAL
path_requested: /manual-ban
reported_at: null
cf_rule_id: null
expiration_at: 2024-12-21 14:00:00
is_blocked: true
already_reported: false
last_seen_at: null
created_at: 2024-12-20 14:00:00
updated_at: 2024-12-20 14:00:00
```

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

### Custom Listener for Honeypot Attacks

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Events.md

Provides an example of creating a custom listener to handle HoneypotAttackDetected events, such as sending email notifications or logging to a custom channel.

```php
namespace App\Listeners;

use HoneypotPlus\Events\HoneypotAttackDetected;

class NotifyAdminsOfAttack
{
    public function handle(HoneypotAttackDetected $event): void
    {
        // Send email notification
        Mail::to('admin@example.com')->send(
            new AttackNotification($event)
        );

        // Or log to a custom channel
        \Log::channel('security')->warning('Honeypot attack detected', [
            'ip' => $event->ip,
            'path' => $event->pathRequested,
        ]);
    }
}
```

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

### Example HoneypotAttackDetected Event Data

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Events.md

Illustrates the typical data structure of a HoneypotAttackDetected event when fired from the middleware, including details for direct pattern matches.

```php
HoneypotAttackDetected {
    ip: "203.0.113.42"
    honeypotRule: "/.env"
    userAgent: "curl/7.68.0"
    httpMethod: "GET"
    pathRequested: "/.env"
}
```

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

### List Blocked IPs Example Output

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Commands.md

Displays a table of the 20 most recent active IP bans, including ID, IP address, triggering rule, expiration time, and user agent.

```bash
Blocked IPs

┌────┬──────────────┬──────────────────────┬──────────────┬────────────────┐
│ ID │ IP           │ Rule                 │ Expires At   │ User Agent     │
├────┼──────────────┼──────────────────────┼──────────────┼────────────────┤
│ 42 │ 192.168.1.1  │ /.env                │ in 20 hours  │ curl/7.68.0    │
│ 41 │ 203.0.113.22 │ /wp-admin            │ in 1 day     │ Mozilla/5.0    │
└────┴──────────────┴──────────────────────┴──────────────┴────────────────┘
```

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

### Install Laravel Honeypot Plus via Composer

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/README.md

Use Composer to require the package. This is the first step in integrating the honeypot functionality into your Laravel application.

```bash
composer require ilogus/laravel-honeypotplus
```

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

### AbuseIPDB API Report Request Example

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Jobs.md

Illustrates the structure of a POST request to the AbuseIPDB report API. This includes required headers and form data such as IP address, categories, and a comment.

```http
POST https://api.abuseipdb.com/api/v2/report
Content-Type: application/x-www-form-urlencoded
Key: {apiKey}
Accept: application/json

ip=192.168.1.1
categories=21,19
comment=[Laravel HoneypotPlus] Automated report - Honeypot access detected on path: /.env via rule: /.env
```

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

### HoneypotPlus Facade Class

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/types.md

Provides a static interface to the HoneypotPlus service. It includes methods for checking bans, retrieving ban records, banning IPs, unbanning IPs, and getting statistics.

```php
final class HoneypotPlus extends Facade {
    protected static function getFacadeAccessor(): string;
}
```

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

### Boot HoneypotPlus Service Provider

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/ServiceProvider.md

The boot method is called after all services are registered to set up runtime behavior. This includes console publishing for config and migrations, registering commands, setting up middleware aliases, event listeners, and scheduler registration.

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

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

### Set Honeypot Plus Schedule Cleanup Frequency

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/configuration.md

Examples of setting the HONEYPOT_PLUS_SCHEDULE_CLEANUP environment variable to control the frequency of the cleanup command. Valid values correspond to Laravel's scheduling methods.

```bash
# Run cleanup every 4 hours
HONEYPOT_PLUS_SCHEDULE_CLEANUP=everyFourMinutes
```

```bash
# Run cleanup weekly
HONEYPOT_PLUS_SCHEDULE_CLEANUP=weekly
```

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

### Publish Configuration and Migrations

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/ServiceProvider.md

Commands to publish the package's configuration file and migration files to the application's respective directories.

```bash
php artisan vendor:publish --provider=HoneypotPlus\HoneypotPlusServiceProvider
```

```bash
php artisan vendor:publish --tag=honeypot-plus:config
```

```bash
php artisan vendor:publish --tag=honeypot-plus:migrations
```

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

### Check HoneypotPlus Status

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/00-START-HERE.md

Verify the installation and status of the HoneypotPlus package within your Laravel application.

```bash
php artisan about | grep HoneypotPlus # Check status
```

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

### Configure Basic HoneypotPlus Settings

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Set environment variables in `.env` to enable core features, logging, ban duration, and HTTP response status.

```bash
# Core
HONEYPOT_PLUS_ENABLE=true
HONEYPOT_PLUS_LOGGING=true

# Ban duration
HONEYPOT_PLUS_BAN_DURATION_HOURS=24

# HTTP response
HONEYPOT_PLUS_EXCEPTION_STATUS=403
```

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

### Disable ServiceProvider in Tests

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/ServiceProvider.md

Use this method in your test setup to prevent the ServiceProvider from being loaded automatically.

```php
$this->withoutProvider("HoneypotPlus\HoneypotPlusServiceProvider"::class);
```

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

### InstallCommand Class Definition

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/types.md

Defines the InstallCommand for the HoneypotPlus package. This command is used to publish the configuration file and the migration for the package.

```php
final class InstallCommand extends Command {
    protected $signature = 'honeypot-plus:install';
    protected $description = 'Install the HoneypotPlus package (publish config & migration)';
    public function handle(): int;
}
```

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

### Get Honeypot Statistics

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/00-START-HERE.md

Retrieve statistics related to honeypot activity, such as the number of blocked requests.

```php
HoneypotPlus::getStats()              // Get statistics
```

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

### Enable HoneypotPlus

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/00-START-HERE.md

Set this configuration key to 'true' to enable the HoneypotPlus package functionality.

```bash
HONEYPOT_PLUS_ENABLE=true
```

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

### Mock ServiceProvider in Tests

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/ServiceProvider.md

Mock the ServiceProvider to control its behavior during testing, for example, by stubbing the 'isBanned' method.

```php
$this->mock("HoneypotPlus\HoneypotPlus"::class, function ($mock) {
    $mock->shouldReceive('isBanned')->andReturn(false);
});
```

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

### Get All Unreported Attacks

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/HoneypotPlusAttack.md

Fetches all attack records that have not yet been reported. Useful for processing new attacks.

```php
$unreported = HoneypotPlusAttack::whereNull('reported_at')->get();
```

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

### Run Test Suite

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/CONTRIBUTING.md

Execute the project's test suite using Composer. This is a standard step before submitting pull requests to ensure code quality.

```bash
composer test
```

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

### Get statistics

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/README.md

Retrieves statistics about the honeypot system, including total, active, expired, and reported entries.

```APIDOC
## Get statistics

### Description
Retrieves statistics about the honeypot system.

### Method
```php
HoneypotPlus::getStats()
```

### Response
#### Success Response
- **stats** (array) - An array containing honeypot statistics.
  - **total** (int) - Total number of entries.
  - **active** (int) - Number of currently active bans.
  - **expired** (int) - Number of expired bans.
  - **reported** (int) - Number of reported incidents.

### Request Example
```php
use HoneypotPlus\Facades\HoneypotPlus;

$stats = HoneypotPlus::getStats();
// $stats will be like: ['total' => 10, 'active' => 5, 'expired' => 3, 'reported' => 2]
```
```

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

### Get HoneypotPlusAttack Statistics

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/HoneypotPlusAttack.md

Calculates various statistics for HoneypotPlusAttack records, including total, active, and reported counts.

```php
$total = HoneypotPlusAttack::count();
$active = HoneypotPlusAttack::active()->count();
$reported = HoneypotPlusAttack::whereNotNull('reported_at')->count();
```

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

### Get Recently Attacked IPs

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/HoneypotPlusAttack.md

Retrieves a list of the 10 most recent attack records, ordered by creation date.

```php
$recent = HoneypotPlusAttack::orderBy('created_at', 'desc')->limit(10)->get();
```

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

### Enable Honeypot Plus via .env

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/configuration.md

Set HONEYPOT_PLUS_ENABLE to true in your .env file to activate the package. Add your Cloudflare API token if using that integration.

```bash
HONEYPOT_PLUS_ENABLE=true
HONEYPOT_PLUS_CLOUDFLARE_API_TOKEN=xxx
```

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

### Get All Active Bans

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/database-schema.md

Retrieves all records from the `honeypot_plus_attacks` table where the `is_blocked` flag is true and the ban has not yet expired.

```php
HoneypotPlusAttack::where('is_blocked', true)
    ->where('expiration_at', '>', now())
    ->get();
```

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

### Set up Cloudflare integration

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/INDEX.md

Configure environment variables to integrate with Cloudflare for enhanced security. This requires your Cloudflare API token and Zone ID.

```bash
HONEYPOT_PLUS_CLOUDFLARE_API_TOKEN=xxx
HONEYPOT_PLUS_CLOUDFLARE_ZONE_ID=xxx
```

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

### Enable HoneypotPlus Logging

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/00-START-HERE.md

Set this configuration key to 'true' to enable logging of honeypot-related events and actions.

```bash
HONEYPOT_PLUS_LOGGING=true
```

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

### Example Expired/Unbanned Record

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/database-schema.md

This record shows a previously blocked entry that has since expired or been unbanned, indicated by 'is_blocked: false'.

```yaml
id: 3
ip: 198.51.100.5
honeypot_rule: /wp-admin
user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
http_method: GET
path_requested: /wp-admin
reported_at: null
cf_rule_id: null
expiration_at: 2024-12-19 15:30:00
is_blocked: false
already_reported: false
last_seen_at: 2024-12-20 11:00:00
created_at: 2024-12-19 12:30:00
updated_at: 2024-12-20 10:00:00
```

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

### Create and Query HoneypotPlusAttack Records

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/types.md

Shows how to create new `HoneypotPlusAttack` records and query existing ones, including filtering for active bans. This is used for managing and tracking blocked IPs.

```php
use HoneypotPlus\Models\HoneypotPlusAttack;

// Create a new attack record
$attack = HoneypotPlusAttack::create([
    'ip' => '192.168.1.1',
    'honeypot_rule' => '/.env',
    'user_agent' => 'curl/7.68.0',
    'http_method' => 'GET',
    'path_requested' => '/.env',
    'expiration_at' => now()->addHours(24),
]);

// Query active bans
$activeBans = HoneypotPlusAttack::active()->get();

// Check if an IP is banned
$isBanned = HoneypotPlusAttack::byIp('192.168.1.1')->active()->exists();
```

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

### Get Attacks by Honeypot Rule

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/database-schema.md

Retrieves all attack records associated with a specific honeypot rule, such as `/.env`, from the `honeypot_plus_attacks` table.

```php
HoneypotPlusAttack::where('honeypot_rule', '/.env')->get();
```

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

### Configure AbuseIPDB Integration

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Add your AbuseIPDB API key and maximum age for reported IPs to `.env` for automatic reporting of malicious IPs.

```bash
HONEYPOT_PLUS_ABUSEIPDB_KEY=your_api_key_here
HONEYPOT_PLUS_ABUSEIPDB_MAX_AGE_DAYS=30
```

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

### Mocking HoneypotPlus Facade in Tests

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Facades.md

Demonstrates how to mock the HoneypotPlus facade in tests using Mockery. This allows you to control the behavior of facade methods during unit testing.

```php
use HoneypotPlus\Facades\HoneypotPlus;

public function test_custom_ban_logic()
{
    HoneypotPlus::shouldReceive('isBanned')
        ->with('192.168.1.1')
        ->andReturn(true);

    $this->assertTrue(HoneypotPlus::isBanned('192.168.1.1'));
}
```

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

### Get Most Targeted Paths

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

A PHP snippet to query the database for the top 10 most frequently targeted paths recorded by Honeypot Plus.

```php
HoneypotPlusAttack::selectRaw('path_requested, COUNT(*) as count')
    ->groupBy('path_requested')
    ->orderByDesc('count')
    ->limit(10)
    ->get();
```

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

### Get Recent Attacks

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/database-schema.md

Fetches the 10 most recent attack records from the `honeypot_plus_attacks` table, ordered by their creation timestamp in descending order.

```php
HoneypotPlusAttack::orderBy('created_at', 'desc')->limit(10)->get();
```

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

### Get Active Ban for an IP

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/HoneypotPlusAttack.md

Retrieves the active ban record for a specific IP address. Ensures the record is currently active.

```php
$record = HoneypotPlusAttack::byIp('192.168.1.1')->active()->first();
```

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

### Get Attacks Not Yet Reported

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/database-schema.md

Fetches all attack records from the `honeypot_plus_attacks` table where the `reported_at` timestamp is null, indicating they have not been reported to AbuseIPDB.

```php
HoneypotPlusAttack::whereNull('reported_at')->get();
```

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

### Manage HoneypotPlus Interactively

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/00-START-HERE.md

Launch the interactive management interface for HoneypotPlus to perform various administrative tasks.

```bash
php artisan honeypot-plus:manage      # Interactive management
```

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

### Get Banned IP Details

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/00-START-HERE.md

Fetch detailed information about a specific banned IP address, including ban duration and reason.

```php
HoneypotPlus::getBannedRecord($ip)    // Get ban details
```

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

### Combine Cleanup Options

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Commands.md

Combine the --force and --dry-run options to preview cleanup actions without confirmation. This allows for a safe, non-interactive preview.

```bash
php artisan honeypot-plus:cleanup --force --dry-run
```

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

### Dependency Injection of HoneypotPlus Service

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/ServiceProvider.md

Demonstrates how the ServiceProvider automatically resolves and injects the HoneypotPlus service into controllers or other classes via constructor property promotion.

```php
// In a controller
public function __construct(protected \HoneypotPlus\HoneypotPlus $honeypot)
{
    // Service is automatically injected
}
```

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

### Run Test Suite with Laravel HoneypotPlus

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/README.md

Execute the test suite for the Laravel HoneypotPlus package. Ensure you are in the package directory before running.

```bash
cd honeypotplus
composer test
```

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

### Configure AbuseIPDB Key

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/00-START-HERE.md

Enter your AbuseIPDB API key for reporting malicious IPs. Replace 'xxx' with your actual key.

```bash
HONEYPOT_PLUS_ABUSEIPDB_KEY=xxx
```

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

### Get Top Attacking IPs

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

A PHP snippet to query the database for the top 10 most frequent attacking IP addresses recorded by Honeypot Plus.

```php
use HoneypotPlus\Models\HoneypotPlusAttack;

HoneypotPlusAttack::selectRaw('ip, COUNT(*) as count')
    ->groupBy('ip')
    ->orderByDesc('count')
    ->limit(10)
    ->get();
```

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

### Get statistics

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/INDEX.md

Retrieve statistics related to honeypot activity. This method returns an array or object containing relevant data. Requires the HoneypotPlus facade.

```php
$stats = HoneypotPlus::getStats();
```

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

### Instance Methods

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/HoneypotPlusAttack.md

Provides methods to interact with individual HoneypotPlusAttack records, such as checking ban status and updating record information.

```APIDOC
## Instance Methods

### isBanned

Determine if this record represents an active ban.

```php
public function isBanned(): bool
```

**Returns**: `bool` — `true` if `is_blocked` is true and `expiration_at` is in the future

**Example**:
```php
$record = HoneypotPlusAttack::find(1);
if ($record->isBanned()) {
    echo 'Still active';
} else {
    echo 'Ban has expired';
}
```

---

### markAsReported

Mark this attack as reported to AbuseIPDB.

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

**Updates**: Sets `reported_at` to current timestamp and `already_reported` to `true`

**Behavior**: Called automatically by `ReportToAbuseIPDB::handle()` after successful submission

**Example**:
```php
$record = HoneypotPlusAttack::find(1);
$record->markAsReported();
```

---

### updateLastSeen

Update the last activity timestamp to now.

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

**Updates**: Sets `last_seen_at` to current timestamp

**Behavior**: Called automatically by `HandleHoneypotAttack` listener when an already-banned IP attempts to access a honeypot

**Example**:
```php
$record = HoneypotPlusAttack::find(1);
$record->updateLastSeen();
```
```

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

### HoneypotPlus Service Methods

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/types.md

Provides methods to check ban status, retrieve ban records, ban IPs, unban IPs, and get service statistics.

```APIDOC
## HoneypotPlus Service Methods

### Description
Provides methods to check ban status, retrieve ban records, ban IPs, unban IPs, and get service statistics.

### Methods

- **`isBanned(string $ip): bool`**
  Checks if a given IP address is currently banned.

- **`getBannedRecord(string $ip): ?HoneypotPlusAttack`**
  Retrieves the ban record for a given IP address.

- **`ban(string $ip, int $hours = 24): HoneypotPlusAttack`**
  Bans a given IP address for a specified number of hours (defaults to 24).

- **`unban(string $ip): bool`**
  Unbans a given IP address.

- **`getStats(): array`**
  Retrieves statistics about the honeypot bans.

### Response for `getStats()`

- **`total`** (int) - Total records in the database.
- **`active`** (int) - Currently active (non-expired) bans.
- **`expired`** (int) - Expired bans.
- **`reported`** (int) - Records reported to AbuseIPDB.

### Example Usage
```php
use HoneypotPlus\Facades\HoneypotPlus;

// Check if an IP is banned
if (HoneypotPlus::isBanned('192.168.1.1')) {
    echo 'IP is banned.';
}

// Get ban record
$record = HoneypotPlus::getBannedRecord('192.168.1.1');

// Ban an IP for 48 hours
HoneypotPlus::ban('192.168.1.1', 48);

// Unban an IP
HoneypotPlus::unban('192.168.1.1');

// Get statistics
$stats = HoneypotPlus::getStats();
// Returns: ['total' => 127, 'active' => 5, 'expired' => 122, 'reported' => 45]
```
```

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

### Get Ban Statistics (PHP)

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Retrieve statistics about IP bans. This includes total bans, active bans, expired bans, and IPs reported to AbuseIPDB.

```php
use HoneypotPlus\Facades\HoneypotPlus;

$stats = HoneypotPlus::getStats();
// Returns:
// [
//     'total' => 127,      // Total records
//     'active' => 5,       // Currently blocked
//     'expired' => 122,    // Expired bans
//     'reported' => 45,    // Reported to AbuseIPDB
// ]
```

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

### Enable Honeypot Plus via config file

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/configuration.md

Configure the package directly in config/honeypot-plus.php. This method allows for programmatic control over settings like 'enabled' and 'cloudflare_api_token'.

```php
return [
    'enabled' => true,
    'cloudflare_api_token' => 'xxx',
];
```

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

### Run Tests with Coverage

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/CONTRIBUTING.md

Execute the test suite and generate a code coverage report using Composer. This helps identify areas of the codebase not adequately tested.

```bash
composer test-coverage
```

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

### Check Database Table Count via Tinker

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Use Laravel Tinker to verify the existence and count of the honeypot attacks table. This helps confirm database setup.

```bash
php artisan tinker
DB::table('honeypot_plus_attacks')->count()
```

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

### ReportToAbuseIPDB Job Constructor

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Jobs.md

Initializes the job with an attack object. This is the primary data carrier for the report.

```php
public function __construct(
HoneypotPlusAttack $attack,
) {
}
```

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

### Get Honeypot Statistics

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Facades.md

Retrieve aggregate statistics about honeypot attacks using the `getStats` static method. This provides insights into total, active, expired, and reported attacks.

```php
static array getStats()
```

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

### Example Automatic Attack Detection Record

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/database-schema.md

This record represents an automatically detected attack, including details like IP address, honeypot rule triggered, and blocking status.

```yaml
id: 1
ip: 203.0.113.42
honeypot_rule: /.env
user_agent: curl/7.68.0
http_method: GET
path_requested: /.env
reported_at: 2024-12-20 10:35:22
cf_rule_id: 6c3e9f2a8d1b4e7c
expiration_at: 2024-12-21 09:30:15
is_blocked: true
already_reported: true
last_seen_at: 2024-12-20 11:15:00
created_at: 2024-12-20 09:30:15
updated_at: 2024-12-20 10:35:22
```

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

### Dry Run Honeypot Cleanup

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Commands.md

Preview the actions that would be taken during cleanup without making any actual changes. This is useful for verifying the command's intended behavior.

```bash
php artisan honeypot-plus:cleanup --dry-run
```

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

### Create HoneypotPlusAttack Records with Factory

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/HoneypotPlusAttack.md

Use the factory to create test records for HoneypotPlusAttack. You can create single records, blocked records, or multiple records at once.

```php
HoneypotPlusAttack::factory()->create();
HoneypotPlusAttack::factory()->blocked()->create();
HoneypotPlusAttack::factory(5)->create();
```

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

### Queued Listener for Honeypot Attacks

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Events.md

Demonstrates how to make a custom listener for HoneypotAttackDetected events run asynchronously by implementing the ShouldQueue interface.

```php
namespace App\Listeners;

use HoneypotPlus\Events\HoneypotAttackDetected;
use Illuminate\Contracts\Queue\ShouldQueue;

class LogAttackAsync implements ShouldQueue
{
    public function handle(HoneypotAttackDetected $event): void
    {
        // This runs asynchronously in the queue
        \Log::warning('Attack: ' . $event->ip);
    }
}
```

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

### Get Honeypot Statistics

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/README.md

Retrieve statistics related to honeypot activity, including total bans, active bans, expired bans, and reported incidents. The output is an associative array.

```php
$stats = HoneypotPlus::getStats();
// ['total' => int, 'active' => int, 'expired' => int, 'reported' => int]
```

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

### Configure Cloudflare Integration

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Add Cloudflare API token and Zone ID to `.env` to enable automatic IP banning via Cloudflare firewall rules.

```bash
HONEYPOT_PLUS_CLOUDFLARE_API_TOKEN=your_token_here
HONEYPOT_PLUS_CLOUDFLARE_ZONE_ID=your_zone_id_here
HONEYPOT_PLUS_BLOCK_CATEGORY=honeypot-probe
```

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

### Dispatching Event from Middleware

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Events.md

Illustrates how the HoneypotPlusMiddleware dispatches the HoneypotAttackDetected event with request details.

```php
event(new HoneypotAttackDetected(
    ip: $request->ip(),
    honeypotRule: $matchedRule,
    userAgent: $request->userAgent(),
    httpMethod: $request->method(),
    pathRequested: $path,
));
```

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

### Run HoneypotPlus Manage Command

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Commands.md

Execute the interactive command to manage blocked IPs. This is the entry point for all interactive operations.

```bash
php artisan honeypot-plus:manage
```

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

### Registering Custom Listener

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Events.md

Shows how to register a custom listener for the HoneypotAttackDetected event in your application's service provider.

```php
Event::listen(
    HoneypotAttackDetected::class,
    App\Listeners\NotifyAdminsOfAttack::class
);
```

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

### HoneypotPlus Logo and Links

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Commands.md

Displays the package name and links to its GitHub repository for issues and general information.

```text
Laravel HoneypotPlus

  https://github.com/ilogus/laravel-honeypotplus
  Found a bug? Open an issue: https://github.com/ilogus/laravel-honeypotplus/issues
```

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

### Get Ban Details for an IP (PHP)

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Retrieve detailed information about a banned IP address. This includes IP, creation time, expiration time, and the honeypot rule that triggered the ban.

```php
use HoneypotPlus\Facades\HoneypotPlus;

$record = HoneypotPlus::getBannedRecord('192.168.1.1');
if ($record) {
    echo $record->ip;
    echo $record->created_at;
    echo $record->expiration_at;
    echo $record->honeypot_rule;
}
```

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

### Add HoneypotPlus Middleware to Application

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Register the HoneypotPlusMiddleware in `bootstrap/app.php` using `append()` to ensure it runs before routing.

```php
use HoneypotPlus\Middleware\HoneypotPlusMiddleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(...)
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->append(HoneypotPlusMiddleware::class); // Add this
    })
    ->withExceptions(...)
    ->create();
```

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

### Configure Queue Workers for Redis

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/integration-guide.md

Set up queue workers to use Redis for faster job processing, which is recommended for high-traffic scenarios. This command starts a worker listening for Redis queues.

```bash
php artisan queue:work redis
```

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

### Listen for HoneypotAttackDetected Event

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/types.md

Demonstrates how to listen for the `HoneypotAttackDetected` event using Laravel's `Event::listen` method. This is useful for custom logging or handling of detected attacks.

```php
use HoneypotPlus\Events\HoneypotAttackDetected;
use Illuminate\Support\Facades\Event;

Event::listen(HoneypotAttackDetected::class, function ($event) {
    echo "Attack detected from {$event->ip} on {$event->pathRequested}";
});
```

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

### Cloudflare API DELETE Request Example

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Jobs.md

Illustrates the structure of the DELETE request to the Cloudflare API for removing a firewall access rule. Ensure your API token and zone ID are correctly configured.

```http
DELETE https://api.cloudflare.com/client/v4/zones/{zoneId}/firewall/access_rules/rules/{ruleId}
Authorization: Bearer {apiToken}
```

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

### Using Real HoneypotPlus Service in Feature Tests

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Facades.md

Shows how to use the actual HoneypotPlus service in feature tests. This involves calling the facade methods directly to test the real functionality, such as banning and unbanning IPs.

```php
public function test_banning_an_ip()
{
    HoneypotPlus::ban('192.168.1.1', 24);
    $this->assertTrue(HoneypotPlus::isBanned('192.168.1.1'));
    
    HoneypotPlus::unban('192.168.1.1');
    $this->assertFalse(HoneypotPlus::isBanned('192.168.1.1'));
}
```

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

### Honeypot Plus Core Settings

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/configuration.md

Environment variables for enabling the honeypot functionality, logging, and setting the HTTP status code for blocked requests.

```bash
HONEYPOT_PLUS_ENABLE=true
HONEYPOT_PLUS_LOGGING=true
HONEYPOT_PLUS_EXCEPTION_STATUS=403
```

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

### Get Banned IP Record

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/Facades.md

Retrieve the active ban record for a specific IP address using the `getBannedRecord` static method. This method returns the ban details or null if the IP is not banned.

```php
static ?HoneypotPlusAttack getBannedRecord(string $ip)
```

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

### Run Test Suite with Coverage

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/README.md

Execute the test suite for the Laravel HoneypotPlus package and generate a code coverage report. This command is useful for assessing test completeness.

```bash
composer test-coverage
```

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

### Get Honeypot Statistics (PHP)

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/HoneypotPlus.md

Retrieves aggregate statistics on honeypot attacks and bans. This includes total attacks, active bans, expired bans, and IPs reported to AbuseIPDB. Requires the HoneypotPlus facade.

```php
use HoneypotPlus\Facades\HoneypotPlus;

$stats = HoneypotPlus::getStats();
echo 'Total attacks: ' . $stats['total'];
echo 'Currently blocked: ' . $stats['active'];
echo 'Reported to AbuseIPDB: ' . $stats['reported'];
```

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

### HoneypotPlus Facade Methods

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/types.md

The HoneypotPlus facade provides static methods to interact with the IP banning system. You can check if an IP is banned, retrieve banned records, ban IPs for a specified duration, unban IPs, and get overall statistics.

```APIDOC
## HoneypotPlus Facade

### Description
Provides static methods to manage IP bans and retrieve statistics.

### Methods

#### `isBanned(string $ip): bool`
Checks if a given IP address is currently banned.

#### `getBannedRecord(string $ip): ?HoneypotPlusAttack`
Retrieves the ban record for a given IP address. Returns null if the IP is not banned.

#### `ban(string $ip, int $hours = 24): HoneypotPlusAttack`
Bans an IP address for a specified number of hours. Defaults to 24 hours.

#### `unban(string $ip): bool`
Removes the ban for a given IP address.

#### `getStats(): array`
Retrieves statistics related to honeypot attacks and bans.

### Usage Example
```php
use HoneypotPlus\Facades\HoneypotPlus;

// Check if an IP is banned
$isBanned = HoneypotPlus::isBanned('192.168.1.1');

// Get banned record
$banRecord = HoneypotPlus::getBannedRecord('192.168.1.1');

// Ban an IP for 48 hours
HoneypotPlus::ban('192.168.1.1', 48);

// Unban an IP
HoneypotPlus::unban('192.168.1.1');

// Get statistics
$stats = HoneypotPlus::getStats();
```
```

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

### HoneypotPlus Configuration Options

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/MANIFEST.txt

Configuration settings for the HoneypotPlus package. Covers core settings, honeypot patterns, ban durations, and integration credentials.

```php
Core: enabled, logging, exception_status
Honeypots: patterns (static and regex)
Ban Duration: hours until expiry
Cloudflare: api_token, zone_id, block_category
AbuseIPDB: api_key, categories, max_age_days
Scheduler: cleanup frequency
```

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

### Mock HoneypotPlus Facade

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/README.md

Use Mockery to mock the HoneypotPlus facade, allowing you to control its behavior in tests, such as simulating a banned IP.

```php
        HoneypotPlus::shouldReceive('isBanned')->andReturn(true);
```

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

### Laravel Honeypot Plus File Structure

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/README.md

Overview of the directory and file structure for the Laravel Honeypot Plus package.

```tree
src/
├── HoneypotPlus.php              # Core service class
├── HoneypotPlusServiceProvider.php  # Package registration
├── Facades/
│   └── HoneypotPlus.php           # Static facade
├── Middleware/
│   └── HoneypotPlusMiddleware.php  # Request interceptor
├── Models/
│   └── HoneypotPlusAttack.php      # Eloquent model
├── Events/
│   └── HoneypotAttackDetected.php  # Event class
├── Listeners/
│   └── HandleHoneypotAttack.php    # Event listener
├── Jobs/
│   ├── BanViaCloudflare.php        # Cloudflare job
│   ├── ReportToAbuseIPDB.php       # AbuseIPDB job
│   └── UnbanFromCloudflare.php     # Unban job
└── Commands/
    ├── InstallCommand.php          # Install command
    ├── ManageCommand.php           # Interactive manage
    └── CleanupCommand.php          # Cleanup command

config/
└── honeypot-plus.php               # Configuration

database/
├── migrations/
│   └── 2024_01_01_000000_create_honeypot_plus_attacks_table.php
└── factories/
    └── HoneypotPlusAttackFactory.php
```

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

### Add HoneypotPlus Information to `php artisan about`

Source: https://github.com/ilogus/laravel-honeypotplus/blob/main/_autodocs/api-reference/ServiceProvider.md

Integrates custom information about the HoneypotPlus package status, logging, and external service configurations (AbuseIPDB, Cloudflare) into the `php artisan about` command output.

```php
AboutCommand::add('HoneypotPlus', fn () => [
    'Status' => config('honeypot-plus.enabled', true) ? 
        '<fg=green;options=bold>Enabled</>' : '<fg=gray;options=bold>Disabled</>',
    'Logging' => config('honeypot-plus.logging', true) ? 'Enabled' : 'Disabled',
    'AbuseIPDB' => ! empty(env('HONEYPOT_PLUS_ABUSEIPDB_KEY')) ? 
        'Configured' : 'Not configured',
    'Cloudflare' => ! empty(env('HONEYPOT_PLUS_CLOUDFLARE_API_TOKEN')) && 
        ! empty(env('HONEYPOT_PLUS_CLOUDFLARE_ZONE_ID')) ? 
        'Configured' : 'Not configured',
]);
```