ZTLayer Logo
Start Building

PHP (Vanilla) Integration Guide

If you are maintaining a legacy PHP application, a custom framework, or simply not using Laravel, you can use our framework-agnostic Vanilla PHP SDK.

1. Installation

Install the base PHP SDK via Composer.

composer require ztlayer/php-core

If you are not using Composer, you can download the .zip from our GitHub releases and require the autoload.php file manually, though Composer is highly recommended.

2. Initialization & Protection

You must invoke the ZTLayer check at the very top of your application's entry point (usually index.php or bootstrap.php), before any output is sent to the browser and before any database connections are made.

<?php
// 1. Require Composer's autoloader
require_once __DIR__ . '/vendor/autoload.php';
 
use ZTLayer\Core\Client as ZTLayer;
use ZTLayer\Core\Config;
 
// 2. Configure the client
$config = new Config([
    'api_key' => getenv('ZTLAYER_API_KEY') ?: 'your_api_key_here',
    'fail_mode' => 'open', // Allow traffic if API is unreachable
    'timeout_ms' => 1500
]);
 
$ztlayer = new ZTLayer($config);
 
// 3. Inspect the current HTTP Request
try {
    // This method automatically parses $_SERVER variables to gather IP and Headers
    $verdict = $ztlayer->inspectCurrentRequest();
 
    if ($verdict->action === 'block') {
        // Stop execution immediately
        http_response_code(403);
        header('Content-Type: application/json');
        echo json_encode(['error' => 'Blocked by ZTLayer Edge Security']);
        exit;
    }
 
    if ($verdict->action === 'challenge') {
        // Redirect to the managed CAPTCHA page
        header('Location: ' . $verdict->challengeUrl);
        exit;
    }
 
    // If action is 'allow', do nothing and let the script continue
} catch (\Exception $e) {
    // Failsafe error handling
    error_log('ZTLayer Security Error: ' . $e->getMessage());
}
 
// ==========================================
// YOUR APPLICATION LOGIC STARTS HERE
// ==========================================
 
echo "Welcome to the secure application!";

3. Handling Reverse Proxies

Unlike modern frameworks like Laravel that have built-in proxy trusting mechanisms, raw PHP applications rely entirely on the $_SERVER superglobal.

If your PHP application sits behind Cloudflare, an AWS Load Balancer, or Nginx, $_SERVER['REMOTE_ADDR'] will contain the IP of the proxy, not the user. You must configure ZTLayer to look at the correct HTTP header.

$config = new Config([
    'api_key' => '...',
    // Tell ZTLayer to use the X-Forwarded-For header instead of REMOTE_ADDR
    'extract_ip_from_header' => 'HTTP_X_FORWARDED_FOR',
]);

Next Steps