haxneeraj/laraguard-ip

A Laravel middleware to guard your application via IP and country-level control.

v1.0.0 2025-04-15 06:06 UTC

Requires

• php: >=8.0
• ext-json: *

Requires (Dev)

• guzzlehttp/guzzle: ^7.0
• guzzlehttp/psr7: ^2.0
• illuminate/console: ^9.0 || ^10.0 || ^11.0 || ^12.0
• illuminate/database: ^9.0 || ^10.0 || ^11.0 || ^12.0
• illuminate/http: ^9.0 || ^10.0 || ^11.0 || ^12.0
• illuminate/support: ^9.0 || ^10.0 || ^11.0 || ^12.0
• larastan/larastan: ^2.9
• laravel/pint: ^1.16
• mockery/mockery: ^1.7
• orchestra/testbench: ^8.18
• phpunit/phpunit: ^10.5
• symfony/http-foundation: ^5.0 || ^6.0 || ^7.0

Suggests

• illuminate/console: For command line integration
• illuminate/database: For exception handling and DB checks
• illuminate/http: For HTTP request handling
• illuminate/support: Required for Laravel integration
• symfony/http-foundation: For response and request objects

MIT

• Neeraj Saini

README

🚫 Laraguard-IP

A powerful Laravel package to protect your application using IP-based, country-based, and spam-blacklist-based middleware.

Created with ❤️ by Neeraj Saini (opens in new tab)

✨ Features

• ✅ IP Whitelist Only Mode
• 🌍 Country Whitelist Mode (GeoIP-based) (COMING SOON)
• ❌ Spam Protection using blocklists (like AbuseIPDB)
• 🧠 IP compression & JSON-based caching
• 🛡️ Middleware-based access control
• 🛠️ Artisan command to fetch & cache spam IPs

📦 Installation

composer require haxneeraj/laraguard-ip

🛠 Configuration

1. Add the Service Provider

Add the service provider to the config/app.php file (this step may be optional if you're using Laravel's package auto-discovery):

For Laravel 10 and below:

    'providers' => [
        // Other service providers...
        Haxneeraj\LaraguardIp\Providers\LaraguardIpServiceProvider::class,
    ],

For Laravel 11: Add the service provider to the bootstrap/providers.php file (this step may be optional if you're using Laravel's package auto-discovery):

    return [
        // Other service providers...
        Haxneeraj\LaraguardIp\Providers\LaraguardIpServiceProvider::class,
    ];

2. Publish the config file

php artisan vendor:publish --provider="Haxneeraj\LaraguardIp\Providers\LaraguardIpServiceProvider" --tag=config

This will create a config file at:

config/laraguard-ip.php

🧹 Middleware Usage

The middleware is automatically registered via the package's service provider.
You can directly use it in your routes like this:

Apply to Routes

Route::middleware(['laraguard-ip'])->group(function () {
    // Protected routes
});

⚙️ Configuration Options

Here's a summary of available config values:

Key	Description	Default
laraguardip_spam_protection	Enable blocklist protection	false
whitelist_only_access	Only allow IPs in whitelist_ips	false
country_whitelist_only	Only allow from country_whitelist	false
whitelist_ips	Safe IPs	['127.0.0.1']
country_whitelist	Allowed ISO country codes	['IN', 'US']
sources	Blocklist sources (URL)	AbuseIPDB
path	Blocklist storage path	storage/framework/cache/laraguard-ip.json
compress	Enable IP compression	true

🔁 Fetch & Cache Blacklist IPs

You can fetch and store the latest spam IPs from the defined sources:

php artisan laraguardip:update

• Downloads IPs from config('laraguard-ip.sources')
• Saves to laraguard-ip.json
• Caches the list forever using Laravel's Cache

❓ How It Works

• ⛔ Denies access if IP is not whitelisted (if enabled)
• 🌍 Blocks requests from unwanted countries (if enabled)
• ❌ Checks IPs against blacklist
• 📂 Cache and config driven – no DB required

🧪 Example .env

LARAGUARDIP_SPAM_PROTECTION=true
LARAGUARDIP_WHITELIST_ONLY=false
LARAGUARDIP_COUNTRY_WHITELIST_ONLY=false
LARAGUARDIP_STORAGE_PATH=framework/cache/laraguard-ip.json
LARAGUARDIP_STORAGE_COMPRESS=true

🧪 Tests

This package comes with feature and unit tests to ensure everything works smoothly.

🏃 Run Tests

composer test

🧠 Want to Contribute?

Pull requests are welcome! Feel free to fork, raise issues or drop ideas.

📄 License

MIT © Neeraj Saini (opens in new tab)