Download the PHP package abdulhadii777/laravel-ip-guard without Composer

Laravel IP Guard

A powerful Laravel middleware package for IP-based access control with whitelist and blacklist support. Protect your application by allowing or blocking specific IP addresses with dynamic database management and a flexible priority system.

Current Version: v0.1.1

Features

• Dynamic Database Management: Add/remove IPs without code changes
• Priority-Based Access Control: Blacklist takes highest priority over whitelist
• Environment Toggle: Enable/disable IP restrictions via environment variable
• Whitelist Support: Allow only specific IPs
• Blacklist Support: Block specific IPs (including * for all IPs)
• Exact IP Matching: Support for exact IP addresses only
• Soft Toggle Control: Enable/disable IPs without deleting records
• Artisan Commands: Full CLI management interface
• Facade Support: Easy programmatic access
• Proxy Support: Works behind load balancers and proxies
• Fallback Support: Falls back to config if database unavailable
• Custom Error Responses: JSON or plain text error responses
• Laravel Integration: Seamless integration with Laravel middleware

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

The package will automatically register itself. You can publish the config file and migration with:

Or use the package's publish commands:

Then run the migration:

Configuration

After publishing the config file, you can configure the package in config/ip-guard.php. The package now uses database-driven IP management by default, with config as fallback:

Database Management

The package now uses database-driven IP management by default. IPs are stored in the ip_guards table with the following structure:

• id: Primary key
• ip_address: The IP address (exact match only)
• type: Either 'whitelist' or 'blacklist'
• description: Optional description for the IP
• is_active: Boolean flag to enable/disable the IP
• created_at / updated_at: Timestamps

Database Schema

Usage

Dynamic IP Management

Via Facade

Via Artisan Commands

Via Model

Basic Middleware Usage

Apply the middleware to routes in your routes/web.php or routes/api.php:

Global Middleware

Add the middleware globally in app/Http/Kernel.php:

Controller Middleware

Apply in your controller constructor:

IP Matching Rules

The package supports exact IP matching only:

Exact IP Matching

Block All IPs

Priority Rules

The middleware follows this priority order:

1. Environment Check: If IP_GUARD_ENABLED=false, all IPs are allowed (no restrictions)
2. Blacklist Check (Highest Priority): If the client IP matches any blacklist rule, access is denied
   • * in blacklist blocks ALL IPs regardless of whitelist
3. Whitelist Check: If whitelist is configured and IP matches, access is allowed
4. Whitelist Enforcement: If whitelist is configured but IP doesn't match, access is denied
5. Default: If whitelist is null/empty and IP is not blacklisted, access is allowed

Examples:

*Scenario 1: Blacklist with ``**

Scenario 2: Normal priority

Scenario 3: No restrictions

Scenario 4: Disabled

Proxy and Load Balancer Support

When your application is behind a proxy or load balancer, configure the ip_header option:

Make sure your Laravel application trusts the proxy by configuring TrustProxies middleware.

Error Responses

JSON Response (default)

Plain Text Response

Configure the response format in the config:

Advanced Examples

Admin Panel Protection

Environment-Based Control

Mixed Blacklist and Whitelist

Block Specific IPs

Development Environment

Temporary IP Management

Testing

The package includes comprehensive tests using Pest 4 with MySQL database testing.

Prerequisites

1. MySQL Database: Ensure MySQL is running and accessible
2. Test Database: Create a test database (or run the setup script)

Running Tests

Test Structure

The test suite includes:

• Unit Tests (tests/Unit/):

  • Models/IpGuardTest.php - Model functionality and scopes
  • Services/LaravelIpGuardTest.php - Service class methods
• Feature Tests (tests/Feature/):
  • Middleware/IpGuardTest.php - Middleware behavior and IP matching
  • Commands/IpGuardCommandTest.php - Artisan command functionality
  • Integration/IpGuardIntegrationTest.php - End-to-end workflows

Test Configuration

Tests use MySQL database with the following configuration:

• Database: laravel_ip_guard_test
• Host: 127.0.0.1
• Port: 3306
• Username: root (configurable)
• Password: Empty (configurable)

Test Coverage

The test suite covers:

• ✅ Model creation, updates, and deletion
• ✅ Database scopes and relationships
• ✅ Service facade methods
• ✅ Middleware IP matching logic
• ✅ Priority system (blacklist > whitelist)
• ✅ Artisan command functionality
• ✅ Error handling and validation
• ✅ Custom headers and configuration
• ✅ Fallback to config when database unavailable
• ✅ Integration workflows
• ✅ Bulk operations
• ✅ Statistics and reporting

Custom Test Configuration

You can customize test database settings in phpunit.xml.dist:

Security Considerations

• Always test your IP rules in a staging environment
• Consider using both whitelist and blacklist for maximum security
• Regularly review and update your IP lists
• Monitor access logs for blocked attempts
• Use HTTPS to prevent IP spoofing

Troubleshooting

Common Issues

1. Middleware not working: Ensure the middleware is properly registered and applied
2. Wrong IP detected: Check your ip_header configuration and proxy setup
3. Blocked legitimate users: Review your whitelist/blacklist rules and priority order
4. IP guard not working: Check if IP_GUARD_ENABLED is set to true in your environment
5. All IPs blocked: Check if * is in your blacklist (this blocks all IPs)
6. Whitelist not working: Remember blacklist takes priority - check if IP is blacklisted first
7. Invalid IP format: Ensure all IPs in your lists are valid IPv4 or IPv6 addresses
8. Database connection issues: Check if migration has been run and database is accessible
9. IP not found in database: Use php artisan ip-guard:manage list to check if IP exists
10. Inactive IPs: Check if IP is disabled using php artisan ip-guard:manage toggle --id=X

Debug Mode

Enable Laravel's debug mode to see detailed error messages:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Abdul Hadi
• All Contributors

License

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