Ipwhitelisting Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require webtoppings/ipwhitelisting
   

2. Publish Config & Migrations

   php artisan vendor:publish --provider="WebToppings\IPWhitelisting\IPWhitelistingServiceProvider"
   php artisan migrate
   

3. First Use Case: Restrict Admin Routes Add the middleware to your routes/web.php or routes/api.php:

   Route::middleware(['auth', 'IPBlocking'])->group(function () {
       // Admin routes here
   });
   

Where to Look First

• Middleware: \WebToppings\IPWhitelisting\Middlewares\IPBlocking
• Controller: \WebToppings\IPWhitelisting\IPWhitelistingController (for managing whitelists)
• Migrations: database/migrations/[timestamp]_create_ip_whitelists_table.php

Implementation Patterns

Core Workflow

1. Whitelist Management

   • Use the published controller (/ipwhitelisting) to add/remove IPs via a CRUD interface.
   • Example route:

     Route::prefix('admin')->middleware(['auth', 'IPBlocking'])->group(function () {
         Route::resource('ipwhitelisting', '\WebToppings\IPWhitelisting\IPWhitelistingController');
     });
     

2. Restricting Access

   • Apply IPBlocking middleware to route groups (e.g., admin, API endpoints).
   • Example for API:

     Route::middleware(['throttle:60', 'IPBlocking'])->prefix('api/v1')->group(...);
     

3. Dynamic Whitelisting

   • Extend the IPWhitelist model (\WebToppings\IPWhitelisting\Models\IPWhitelist) to add logic (e.g., auto-whitelist trusted subnets):

     use WebToppings\IPWhitelisting\Models\IPWhitelist;
     
     IPWhitelist::create(['ip_address' => '192.168.1.0/24']);
     

Integration Tips

• APIs: Combine with api middleware group for granular control:

  Route::middleware(['auth:api', 'IPBlocking'])->get('/admin-data', ...);
  

• Testing: Mock the middleware in PHPUnit:

  $this->app->instance(\WebToppings\IPWhitelisting\Middlewares\IPBlocking::class, function () {
      return new class {
          public function handle($request, Closure $next) { return $next($request); }
      };
  });
  

• Subnets: Use CIDR notation (e.g., 10.0.0.0/8) for bulk whitelisting.

Gotchas and Tips

Pitfalls

1. Middleware Order Matters

   • Place IPBlocking before auth if you want to block unauthenticated users by IP first:

     Route::middleware(['IPBlocking', 'auth'])->group(...); // Blocks IP first
     

2. IPv6 Support

   • The package defaults to IPv4. For IPv6, extend the IPWhitelist model’s validateIp() method or use a regex like:

     if (!filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) { ... }
     

3. Caching Headaches

   • If using IPBlocking with cached routes (e.g., php artisan route:cache), clear the cache after adding/removing IPs:

     php artisan route:clear
     

4. False Positives

   • Cloud providers (AWS, GCP) may show different IPs for users. Whitelist the provider’s IP ranges instead of individual IPs.

Debugging

• Check Whitelisted IPs Run this Artisan command to verify entries:

  php artisan tinker
  >>> \WebToppings\IPWhitelisting\Models\IPWhitelist::all();
  

• Log Blocked Requests Extend the middleware to log blocked IPs:

  use Illuminate\Support\Facades\Log;
  
  public function handle($request, Closure $next) {
      if (!$this->isWhitelisted($request)) {
          Log::warning("Blocked IP: {$request->ip()}");
          abort(403);
      }
      return $next($request);
  }
  

Extension Points

1. Custom Block Page Override the 403 template by publishing views:

   php artisan vendor:publish --tag=ipwhitelisting-views
   

   Then modify resources/views/vendor/ipwhitelisting/403.blade.php.

2. Dynamic Whitelisting via API Create an API endpoint to add IPs programmatically:

   Route::post('/whitelist-ip', function (Request $request) {
       $validated = $request->validate(['ip' => 'required|ip']);
       \WebToppings\IPWhitelisting\Models\IPWhitelist::create($validated);
       return response()->json(['success' => true]);
   });
   

3. IP Range Validation Add a custom validator for CIDR ranges:

   use WebToppings\IPWhitelisting\Rules\ValidCidr;
   
   $request->validate(['ip' => ['required', new ValidCidr]]);