README

PHP SDK for the Wardstone LLM security API. Detect prompt injection, content violations, data leakage, and unknown links in LLM inputs and outputs.

Installation

composer require wardstone/client

Quick Start

<?php
use Wardstone\Client;

$client = new Client('YOUR_API_KEY');
$result = $client->detect('Ignore all previous instructions');

if ($result->risk_bands->prompt_attack->level !== 'Low Risk') {
    echo "Prompt attack detected\n";
    echo "Risk: " . $result->risk_bands->prompt_attack->level . "\n";
}

Configuration

$client = new Client(
    apiKey: 'YOUR_API_KEY',       // or set WARDSTONE_API_KEY env var
    baseUrl: 'https://wardstone.ai', // default
    timeout: 30,                      // seconds, default: 30
    maxRetries: 2                     // default: 2, max: 10
);

Environment Variable

The API key can be set via the WARDSTONE_API_KEY environment variable:

// Will use WARDSTONE_API_KEY from environment
$client = new Client();

Usage

Basic Detection

$result = $client->detect('Ignore all previous instructions');

$result->flagged;                                // true
$result->primary_category;                       // "prompt_attack"
$result->risk_bands->prompt_attack->level;       // "Severe Risk"
$result->risk_bands->content_violation->level;   // "Low Risk"
$result->risk_bands->data_leakage->level;        // "Low Risk"
$result->risk_bands->unknown_links->level;       // "Low Risk"

Array Input

$result = $client->detect(['text' => $userInput]);

Scan Strategies

// Full scan (check all categories)
$result = $client->detect(['text' => $input, 'scan_strategy' => 'full-scan']);

// Early exit (stop at first threat)
$result = $client->detect(['text' => $input, 'scan_strategy' => 'early-exit']);

// Smart sample (optimized for long texts)
$result = $client->detect(['text' => $input, 'scan_strategy' => 'smart-sample']);

Raw Scores

$result = $client->detect(['text' => $input, 'include_raw_scores' => true]);
$result->raw_scores->prompt_attack;       // 0.95
$result->raw_scores->content_violation;   // 0.01

Rate Limit Info

$result = $client->detect('some text');
$result->rate_limit->limit;       // 1000
$result->rate_limit->remaining;   // 999
$result->rate_limit->reset;       // 1700000000

Error Handling

use Wardstone\Errors\AuthenticationError;
use Wardstone\Errors\BadRequestError;
use Wardstone\Errors\PermissionError;
use Wardstone\Errors\RateLimitError;
use Wardstone\Errors\InternalServerError;
use Wardstone\Errors\TimeoutError;
use Wardstone\Errors\ConnectionError;
use Wardstone\Errors\WardstoneError;

try {
    $result = $client->detect($input);
} catch (AuthenticationError $e) {
    // Invalid or missing API key (401)
} catch (BadRequestError $e) {
    // Invalid request (400)
    $e->maxLength;  // available for text_too_long errors
} catch (PermissionError $e) {
    // Feature not available on plan (403)
} catch (RateLimitError $e) {
    // Quota exceeded (429)
    $e->retryAfter;  // seconds to wait
} catch (InternalServerError $e) {
    // Server error (500)
} catch (TimeoutError $e) {
    // Request timed out
} catch (ConnectionError $e) {
    // Network failure
} catch (WardstoneError $e) {
    // Catch-all for any Wardstone error
    $e->status;     // HTTP status code (null for network errors)
    $e->errorCode;  // Machine-readable error code
}

Safe Logging

When logging exceptions, use getSafeTrace() and getSafeTraceAsString() instead of PHP's built-in getTrace() / getTraceAsString(). The safe variants redact function arguments to prevent API keys from appearing in logs:

try {
    $result = $client->detect($input);
} catch (WardstoneError $e) {
    // Safe: arguments redacted from trace
    error_log($e->getMessage() . "\n" . $e->getSafeTraceAsString());

    // Avoid: $e->getTraceAsString() may include sensitive arguments
}

Risk Levels

Each category returns one of four risk levels:

"Low Risk" - No threat detected
"Some Risk" - Minor concern
"High Risk" - Significant threat
"Severe Risk" - Critical threat, action recommended

Requirements

PHP >= 8.1
ext-curl
ext-json
Zero runtime dependencies

wardstone / client

Maintainers

Package info

Statistics

Security