Laravel Laravel Package

Getting Started

Install the SDK and its required core dependency (v2.2.4 pins vpndetection-io/vpndetection to ^4.8.0, which is what exposes isPubproxy() and the pubproxy detail payload):

composer require vpndetection-io/sdk-php-laravel
php artisan vendor:publish --tag=vpndetection-config

Set VPNDETECTION_API_KEY in .env. Look first at config/vpndetection.php (cache TTL, base URL, timeout) and the package facade (VpnDetection). A typical first use case is gating registration or checkout:

use VpnDetectionIo\Laravel\Facades\VpnDetection;

$result = VpnDetection::check($request->ip());

if ($result->isVpn() || $result->isProxy() || $result->isPubproxy()) {
    abort(403, 'VPN/proxy connections are not allowed.');
}

If you are upgrading an existing install, confirm vpndetection-io/vpndetection resolved to 4.8.0+ before calling isPubproxy(); older 4.x versions will fail with an undefined-method error.

Implementation Patterns

• Middleware for route-level enforcement. Wrap sensitive routes (registration, login, checkout) with a middleware that resolves the client IP, calls the SDK, and short-circuits with a 403 or redirect. Keep the check behind a config flag so you can disable it per environment.
• Validation rule. Implement a custom rule (NoVpnOrProxy) that returns a validation message rather than aborting, which plays better with form-based flows and Inertia/Livewire responses.
• Service injection for testability. Type-hint the SDK client or facade rather than calling static helpers directly. In tests, swap the underlying client with a fake so feature tests don't hit the network.
• Cache aggressively by IP. VPN status is stable on short horizons. Use the package's cache options or wrap calls in Cache::remember("vpn:{$ip}", now()->addMinutes(30), ...) to avoid burning API quota and adding latency to every request.
• Use detail payloads selectively. Only call details()/pubproxy detail methods when you actually need the reason (e.g. abuse review dashboards). For allow/deny gates, the boolean checks (isVpn, isProxy, isPubproxy) are cheaper and clearer.
• Async enrichment. For non-blocking use cases (risk scoring, analytics), dispatch a queued job to run detection and persist the result to your users/orders table instead of blocking the request.
• Combine signals. Treat isPubproxy as one signal among VPN/proxy/Tor checks. A public proxy hit is high-confidence, but don't equate a clean result with "safe" — layer it with rate limiting and device fingerprinting.

Gotchas and Tips

• Dependency alignment. v2.2.4 is effectively a dependency bump: isPubproxy() and pubproxy details require vpndetection-io/vpndetection 4.8.0. Run composer update vpndetection-io/sdk-php-laravel vpndetection-io/vpndetection together and check composer.lock if you see Call to undefined method.
• Private and reserved IPs. Localhost, RFC1918, and IPv6 link-local addresses typically return no meaningful result. Guard with filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) before calling the API.
• Client IP behind proxies. $request->ip() may return your load balancer unless TrustProxies is configured. Verify X-Forwarded-For handling before trusting a "clean" result.
• Rate limits and timeouts. The API is remote; set a low connect/read timeout in config and always fail open (or fail closed deliberately) in a try/catch. Don't let an SDK outage take down login.
• Cache poisoning by header spoofing. If you cache by IP, make sure the IP is derived from a trusted source; otherwise an attacker can vary X-Forwarded-For to bypass cached blocks.
• Config caching. After changing config/vpndetection.php, run php artisan config:clear in local/dev. In production, config:cache will freeze env values — never call env() at runtime.
• Testing. Bind a fake response in TestCase or use Laravel's Http::fake() if the SDK is HTTP-backed. Assert both the allow and deny paths, including the new pubproxy branch.
• Extension points. Keep business rules (which signals block, which only flag) in your own policy/action class rather than in middleware, so adding future signals (e.g. new detection types) is a one-line change.