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

Parameter	Type	Default	Description
`apiKey`	`string`	(required)	Your SOCWarden API key
`endpoint`	`string`	(required)	SOCWarden ingestor base URL
`timeout`	`int`	`5`	HTTP timeout in seconds
`autoContext`	`bool`	`true`	Auto-collect server/request context
`browserContextHeader`	`string`	`X-SOCWarden-Context`	Header for browser-side context JSON

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

soc-warden / php-sdk

Maintainers

Package info

Statistics

Security