README

PHP SDK for the Deflect Bot Protection API.

Requirements

• PHP 7.4 or higher
• cURL extension
• JSON extension

Installation

Install via Composer:

composer require deflect/deflect-php

Or add to your composer.json:

{
    "require": {
        "deflect/deflect-php": "^1.0"
    }
}

Quick Start

use Deflect\Client;
use Deflect\DeflectError;

// Initialize the client
$client = new Client([
    'api_key' => 'YOUR_API_KEY',
    'action_id' => 'YOUR_ACTION_ID',
]);

try {
    // Get verdict for a session token
    $verdict = $client->getVerdict(['token' => 'session-token-from-client']);
        'token' => 'session-token-from-client',
    ]);
    
    // Check if user can pass
    if ($verdict->verdict !== null && $verdict->verdict->canPass === true) {
        echo "User allowed\n";
        // Allow user to proceed
    } else {
        echo "User blocked\n";
        // Block or challenge user
    }
    
    // Access additional information
    if ($verdict->ip !== null) {
        echo "IP Address: " . $verdict->ip->address . "\n";
        echo "Is VPN: " . ($verdict->ip->isVPN ? 'Yes' : 'No') . "\n";
    }
    
    if ($verdict->location !== null) {
        echo "Country: " . $verdict->location->country . "\n";
    }
    
} catch (DeflectError $e) {
    echo "Error: " . $e->getMessage() . "\n";
    echo "Status: " . $e->getStatus() . "\n";
}

Intelligence APIs

The SDK also provides intelligence endpoints for analyzing emails, phone numbers, and IP addresses:

Email Intelligence

$emailIntel = $client->getEmailIntelligence('user@example.com');

if ($emailIntel->data !== null) {
    if (!$emailIntel->data->isValid) {
        echo "Invalid email format\n";
    }
    
    if (!$emailIntel->data->isTrusted) {
        echo "Untrusted email domain\n";
    }
    
    echo "Trust Score: " . $emailIntel->data->trustScore . "\n";
    echo "Normalized: " . $emailIntel->data->normalizedEmail . "\n";
}

Phone Intelligence

$phoneIntel = $client->getPhoneIntelligence('+1234567890');

if ($phoneIntel->data !== null) {
    if (!$phoneIntel->data->isValid) {
        echo "Invalid phone number\n";
    }
    
    echo "Country: " . $phoneIntel->data->country . "\n";
    echo "Carrier: " . $phoneIntel->data->carrier . "\n";
    echo "Line Type: " . $phoneIntel->data->lineType . "\n";
    echo "Risk Score: " . $phoneIntel->data->riskScore . "\n";
    
    if ($phoneIntel->data->isDisposable || $phoneIntel->data->isVirtual) {
        echo "Suspicious phone number\n";
    }
}

IP Intelligence

$ipIntel = $client->getIpIntelligence('8.8.8.8');

if ($ipIntel->data !== null) {
    if ($ipIntel->data->isVpn || $ipIntel->data->isProxy) {
        echo "VPN or Proxy detected\n";
    }
    
    if ($ipIntel->data->isTorNode) {
        echo "Tor exit node detected\n";
    }
    
    echo "Location: {$ipIntel->data->city}, {$ipIntel->data->country}\n";
    echo "ISP: {$ipIntel->data->isp}\n";
}

Configuration Options

The Client constructor accepts an array with the following options:

Note: action_id is only required when using getVerdict(). Intelligence endpoints (getEmailIntelligence(), getPhoneIntelligence(), getIpIntelligence()) only require api_key.

Example with Custom Options

$client = new Client([
    'api_key' => 'YOUR_API_KEY',
    'action_id' => 'YOUR_ACTION_ID',
    'base_url' => 'https://custom-api.deflect.bot',
    'timeout' => 10,
    'max_retries' => 2,
]);

Error Handling

All errors throw a DeflectError exception with the following methods:

try {
    $verdict = $client->getVerdict($token);
} catch (DeflectError $e) {
    $message = $e->getMessage();  // Error message
    $status = $e->getStatus();     // HTTP status code (0 if not applicable)
    $body = $e->getBody();         // Response body (null if not applicable)
}

Response Structures

VerdictResponse

The VerdictResponse object contains:

Properties

• success (bool): Indicates if the request was successful
• verdict (Verdict|null): Verdict decision
  • canPass (bool|null): Whether the user should be allowed
• device (Device|null): Device information
  • fingerprint (string|null): Device fingerprint
  • userAgent (string|null): User agent string
  • languages (string|null): Browser languages
  • timezone (string|null): Device timezone
  • os (string|null): Operating system
  • isMobile (bool|null): Is mobile device
• ip (IPInfo|null): IP information
  • address (string|null): IP address
  • type (string|null): IP type (e.g., "IPv4", "IPv6")
  • isDatacenter (bool|null): Is datacenter IP
  • isProxy (bool|null): Is proxy
  • isTor (bool|null): Is Tor exit node
  • isVPN (bool|null): Is VPN
  • isThreat (bool|null): Is known threat
  • isBogon (bool|null): Is bogon IP
  • asn (string|null): ASN name
  • asnNumber (int|null): ASN number
• location (Location|null): Geographic location
  • city (string|null): City name
  • postalCode (string|null): Postal/ZIP code
  • country (string|null): Country code
  • continent (string|null): Continent code
  • latitude (float|null): Latitude
  • longitude (float|null): Longitude
• session (Session|null): Session timing
  • startedAt (string|null): Session start time (ISO 8601)
  • finishedAt (string|null): Session finish time (ISO 8601)

EmailIntelligenceResponse

• success (bool): Request success status
• data (EmailIntelligenceData|null): Email analysis data
  • isValid (bool|null): Email format is valid
  • isTrusted (bool|null): Email domain is trusted
  • trustScore (int|null): Trust score (0-100)
  • hasAliasing (bool|null): Email uses aliasing (+ or .)
  • normalizedEmail (string|null): Normalized email address
  • domain (string|null): Email domain
• message (string|null): Additional message

PhoneIntelligenceResponse

• success (bool): Request success status
• data (PhoneIntelligenceData|null): Phone analysis data
  • isValid (bool|null): Phone number is valid
  • e164Format (string|null): E.164 formatted number
  • countryCode (string|null): Country code
  • country (string|null): Country ISO code
  • countryName (string|null): Country name
  • numberType (string|null): Number type
  • lineType (string|null): Line type (mobile, landline, etc.)
  • carrier (string|null): Carrier name
  • carrierType (string|null): Carrier type
  • riskScore (int|null): Risk score
  • isDisposable (bool|null): Is disposable number
  • isVirtual (bool|null): Is virtual number
  • isThreat (bool|null): Is known threat
  • isSpam (bool|null): Is spam number
  • lastUpdated (string|null): Last update time
• message (string|null): Additional message

IpIntelligenceResponse

• success (bool): Request success status
• data (IpIntelligenceData|null): IP analysis data
  • isVpn (bool|null): Is VPN
  • isDatacenterProxy (bool|null): Is datacenter proxy
  • isResidentialProxy (bool|null): Is residential proxy
  • isBogon (bool|null): Is bogon IP
  • isTorNode (bool|null): Is Tor exit node
  • isThreat (bool|null): Is known threat
  • city (string|null): City name
  • postalCode (string|null): Postal code
  • country (string|null): Country code
  • continent (string|null): Continent code
  • latitude (float|null): Latitude
  • longitude (float|null): Longitude
  • asnNumber (int|null): ASN number
  • asnOrganization (string|null): ASN organization
  • isp (string|null): ISP name
• message (string|null): Additional message

Framework Integration

Laravel

// In your controller
public function login(Request $request, Client $deflect)
{
    $verdict = $deflect->getVerdict([
        'token' => $request->input('deflect_token'),
        'email' => $request->input('email'), // Optional
    ]);
    
    if ($verdict->verdict?->canPass !== true) {
        return response()->json(['error' => 'Blocked'], 403);
    }
}

License

MIT