Laravel Integration Guide

The @ztlayer/laravel package provides a native HTTP Middleware that intercepts incoming requests, queries the ZTLayer Edge network, and automatically aborts malicious traffic before it reaches your Controllers.

1. Installation

Install the package via Composer.

composer require ztlayer/laravel

Publish the configuration file:

php artisan vendor:publish --provider="ZTLayer\Laravel\ZTLayerServiceProvider"

2. Configuration

Add your ZTLayer API Key to your .env file.

ZTLAYER_API_KEY="zt_live_xxxxxxxxxxxxxxxxxxxxxxxx"
# Optional: Set to true in local dev to bypass the network check entirely
ZTLAYER_BYPASS_LOCAL=false 

The published config/ztlayer.php file allows you to customize the failover behavior and timeouts.

// config/ztlayer.php
return [
    'api_key' => env('ZTLAYER_API_KEY'),
    'timeout_ms' => 1500,
    
    // 'open' means traffic is allowed if the API is unreachable
    // 'closed' means traffic is blocked (HTTP 503) if the API is unreachable
    'fail_mode' => 'open', 
    
    // Automatically trust proxies like AWS ALB, Cloudflare, or Nginx
    'trust_proxies' => true,
];

3. Registering the Middleware

Depending on your needs, you can protect the entire application globally, or only specific route groups.

Option A: Global Protection (Recommended)

To protect your entire application, add the middleware to the global HTTP stack in app/Http/Kernel.php.

// app/Http/Kernel.php
 
protected $middleware = [
    // Add ZTLayer near the top, right after trusting proxies
    \App\Http\Middleware\TrustProxies::class,
    \ZTLayer\Laravel\Middleware\ZeroTrust::class, 
    \Illuminate\Http\Middleware\HandleCors::class,
    // ...
];

Option B: Route Group Protection

If you only want to protect your api routes or a specific admin panel:

// app/Http/Kernel.php
 
protected $middlewareGroups = [
    'api' => [
        \ZTLayer\Laravel\Middleware\ZeroTrust::class,
        \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        'throttle:api',
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ],
];

4. Handling Webhooks (Bypassing ZTLayer)

If you are using Laravel Cashier to receive Stripe Webhooks, or taking payloads from GitHub/Mailgun, you should bypass ZTLayer for those specific routes to prevent false positives.

// app/Http/Middleware/ZeroTrust.php (If you extend the base middleware)
// OR in config/ztlayer.php
 
return [
    'exclude_routes' => [
        'stripe/webhook',
        'github/webhook'
    ]
];

5. Troubleshooting Laravel Deployments

Issue: Every request is showing the Server IP (e.g., 127.0.0.1 or 10.0.x.x)

Cause: Your Laravel app is behind a reverse proxy (like Nginx, AWS ALB, or Laravel Forge) and TrustProxies is not configured correctly. ZTLayer needs the real client IP. Fix: Ensure App\Http\Middleware\TrustProxies is correctly configured in your Laravel app to trust your load balancer, so that $request->ip() returns the public IP of the user, not the internal IP of the proxy.