Ip Access Laravel Package

Getting Started

This assessment is based on the v2.8.0 release notes only (no prior review, no repo metadata). The package provides IP-whitelist access control for Laravel via middleware, a config whitelist, and an IPACCESS_WHITELIST env variable. Substitute <vendor>/<package> with the actual Packagist name.

1. Install

   composer require <vendor>/<package>
   

   As of v2.8.0, laravel/nova is not installed for you. You onlyneed it if you want the bundled Nova resource to manage whitelist entries in the UI:

   composer require laravel/nova   # optional
   

2. Publish and read the config

   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
   

   Open the published config first — it is the source of truth for whitelist storage, response behaviour, and any bypass rules. Then read the middleware class to confirm exactly which request attribute it inspects (see Gotchas on proxies).

3. Set the whitelist

   IPACCESS_WHITELIST="203.0.113.10,203.0.113.11,10.0.0.0/8"
   

   Or edit the whitelist array in the config file. Pick one; do not maintain both.

4. Register the middleware

   • Laravel 11+: bootstrap/app.php → ->withMiddleware(fn ($m) => $m->alias(['ipaccess' => ...])), or append globally.
   • Laravel 10 and below: app/Http/Kernel.php.

5. First use case — lock down an admin surface:

   Route::middleware('ipaccess')->prefix('admin')->group(function () {
       // ...
   });
   

   Then hit the route from a non-whitelisted IP and confirm the rejection response (403 or redirect, per config) before rolling it out further.

Implementation Patterns

• Route-group scoping over global middleware. Attaching ipaccess to /admin, /internal, or /horizon is usually the right granularity. Global registration locks the whole app, including health checks and webhook endpoints — reserve it for staging environments.
• Layer it with auth, not instead of auth. IP allowlisting is a network control; it should sit in front of auth so unauthorised IPs never touch session/DB work, but it does not replace authentication.
• Environment-driven whitelists. Keep office/VPN ranges in .env (or a per-environment config override) and leave the committed config with safe defaults. This is what IPACCESS_WHITELIST is for — treat the config array as the fallback.
• Nova resource (optional in v2.8.0). If Nova is installed, register the bundled resource in NovaServiceProvider::resources() so operators can add/remove IPs without a deploy. If Nova is absent, skip this entirely — nothing else in the package depends on it. This makes a good pattern: env var for static infrastructure ranges, Nova for ad-hoc operational entries.
• Programmatic checks. If the package exposes a helper/service (check the source), you can gate individual actions — e.g. a Gate::define('internal-only', ...) guard for a sensitive export endpoint — rather than blocking an entire route group.
• Testing. Use $this->withoutMiddleware(IpAccess::class) (or the alias) in feature tests so IP rules don't leak into your test suite, and add one dedicated test that spoofs REMOTE_ADDR to assert the rejection path.
• Deployment. php artisan config:cache is standard in deploy pipelines; any .env change to IPACCESS_WHITELIST requires a re-cache (or config:clear) to take effect.

Gotchas and Tips

• Proxies and load balancers are the #1 failure mode. Behind Cloudflare, an ALB, or nginx, $request->ip() is the proxy address unless TrustProxies is configured. Whitelisting your users' IPs then silently blocks everyone (or allows the proxy). Fix TrustProxies first, then debug the package.
• Empty-whitelist semantics. Determine whether an empty whitelist means "allow all" or "deny all". If the former, a config-cache or env-parse failure quietly opens the door. If the latter, a missing env var locks out production. Test both.
• Env var parsing. IPACCESS_WHITELIST is comma-separated — watch for spaces, trailing commas, and quoted values in .env. Also confirm precedence between the env var and the config array so you don't end up debugging a value that was overridden.
• env() outside config files. If the package calls env('IPACCESS_WHITELIST') directly rather than through a config key, it returns null once the config is cached. Verify the read path; if it's direct, that's a bug worth reporting.
• IPv6 and CIDR. Confirm whether CIDR ranges and IPv6 are supported and how addresses are normalised. An IPv4-mapped IPv6 address (::ffff:203.0.113.10) compared against a plain IPv4 string is a classic mismatch.
• Middleware order. Register before session/auth middleware to avoid unnecessary work and to keep blocked requests out of logs that assume an authenticated user.
• Response behaviour. Check whether rejection is a 403, a 404, or a redirect. A 404 is often preferable for public-facing endpoints so you don't confirm the route exists.
• Upgrading to v2.8.0. No action required for non-Nova apps — this is the point of the release. If you previously had laravel/nova pulled in transitively and now depend on the bundled resource, add it explicitly to require; otherwise the resource class won't be autoloadable. After upgrading, confirm the service provider only registers the Nova resource when the class exists (otherwise nova:install-less apps can hit a class-not-found on boot).
• Extension points. Publish the config and override the middleware via container binding rather than editing vendor code. If you need a custom response, check whether the package exposes a configurable handler/redirect before subclassing the middleware.