README

Framework-agnostic PHP SDK for SOCWarden security observability. Works with any PHP 8.2+ application -- no Laravel or Symfony dependency required.

Installation

composer require soc-warden/php-sdk

Quick Start

use SOCWarden\SOCWarden;

$soc = new SOCWarden(
    apiKey:   'your-api-key',
    endpoint: 'https://ingestor.socwarden.com',
);

// Simple tracking with named arguments
$soc->track('auth.login.success', actorId: 'usr_123', actorEmail: 'john@example.com');

// Track with metadata
$soc->track('data.exported', actorId: 'usr_456', metadata: ['format' => 'csv', 'rows' => 1500]);

Fluent Event Builder

$soc->event('auth.login.failure')
    ->actorEmail('john@example.com')
    ->ip('203.0.113.42')
    ->meta('reason', 'invalid_password')
    ->meta('attempt', 3)
    ->send();

$soc->event('data.exported')
    ->actor('usr_123', 'john@example.com')
    ->resource('Report', 42)
    ->metadata(['format' => 'csv', 'rows' => 1500])
    ->timestamp(new \DateTimeImmutable())
    ->severity('medium')
    ->send();

Raw Data Array

$soc->trackData('auth.login.success', [
    'actor_id'    => 'usr_123',
    'actor_email' => 'john@example.com',
    'ip'          => '203.0.113.42',
    'user_agent'  => 'Mozilla/5.0 ...',
    'metadata'    => ['role' => 'admin'],
]);

PSR-15 Middleware (Slim, Mezzio, etc.)

The SDK ships with a PSR-15 middleware that automatically captures request context (method, path, query string, IP, user agent, referer) and attaches it to every tracked event.

Slim 4

use SOCWarden\SOCWarden;
use SOCWarden\Middleware\PSR15Middleware;
use Slim\Factory\AppFactory;

$soc = new SOCWarden(
    apiKey:   'your-api-key',
    endpoint: 'https://ingestor.socwarden.com',
);

$app = AppFactory::create();
$app->add(new PSR15Middleware($soc));

$app->post('/login', function ($request, $response) use ($soc) {
    // Request context is automatically captured
    $soc->track('auth.login.success', actorId: $userId);
    // ...
});

Mezzio (Laminas)

// config/pipeline.php
$app->pipe(new \SOCWarden\Middleware\PSR15Middleware($container->get(\SOCWarden\SOCWarden::class)));

Manual Request Context

If you are not using PSR-15 middleware, you can set the request manually:

// Any PSR-7 ServerRequestInterface
$soc->setRequest($psrRequest);

// Now all tracked events include request context
$soc->track('auth.login.success', actorId: 'usr_123');

Constructor Options

Auto-Context

When autoContext is enabled (default), every event automatically includes:

• SDK info: name (socwarden-php), version
• Server info: hostname, PHP version, PID
• Request info (when a PSR-7 request is set): method, path, sanitized query string, referer, origin, content type, accept language, request ID
• Browser context: parsed from the X-SOCWarden-Context header (set by the browser SDK)

Sensitive query string parameters (token, key, password, secret, code, auth, session, csrf) are automatically redacted.

Rate Limit Handling

The SDK automatically handles HTTP 429 responses with file-based backoff:

• On 429, the SDK backs off for 1 hour (or the server's Retry-After value)
• During backoff, a probe request is sent every 5 minutes to check if quota is restored
• On success, the backoff is automatically cleared
• Backoff state is stored in sys_get_temp_dir() so it persists across requests

Event Type Format

Event types must match the pattern: ^[a-z][a-z0-9]{0,29}(\.[a-z][a-z0-9_]{0,29}){1,3}$

Examples: auth.login.success, data.exported, server.ssh.login.failure

License

MIT