README

Thin PHP client for the Subzero tokenization vault.

Configure entity types, API keys, and reveal policies in the dashboard first. This SDK is for server-side vault operations only.

Requirements

• PHP 8.1+
• Composer

Install

cd php-sdk
composer install

In another project:

composer require the-iceberg-company/subzero

Quick start

use Iceberg\Subzero\SubzeroClient;

$client = new SubzeroClient(
    tokenizeKey: 'sz_live_...',   // tokenize + search + batch
    revealKey: 'sz_live_...',     // reveal
);
$client->ready();

$token = $client->tokenize('SSN', '123-45-6789');
$found = $client->search('SSN', '123-45-6789');
$value = $client->reveal($token);
$resolved = $client->resolve('123-45-6789');

Or from environment variables:

$client = SubzeroClient::fromEnv();
$client->ready();

A single apiKey works when one key has both scopes (e.g. admin):

$client = new SubzeroClient(apiKey: 'sz_live_...');

API key scopes

Use separate tokenizeKey, revealKey, and proxyKey in production for least privilege.

Reveal caller context (audit)

By default, reveal, resolve, and createRevealGrant attach optional caller_context for audit logging. Auto-capture uses the first frame outside Iceberg\Subzero\ when enabled (default).

use Iceberg\Subzero\Models\RevealCallerContext;

$client = new SubzeroClient(revealKey: '...', captureCallerContext: false);
$client->reveal($token, new RevealCallerContext(file: 'Billing.php', line: 42, sdk: 'php'));

Privacy: auto-capture may include file paths in audit logs — disable or pass opaque refs if needed.

Environment variables

LLM proxy preview

Dry-run scan, discover, and restructure. No upstream LLM call.

$scan = $client->proxy->scan(
    messages: [['role' => 'user', 'content' => 'Patient SSN 123-45-6789']],
);

$discover = $client->proxy->discover(
    messages: [['role' => 'user', 'content' => 'Patient SSN 123-45-6789']],
);

$result = $client->proxy->restructure(
    messages: [['role' => 'assistant', 'content' => 'SSN on file: [SSN_abc12345]']],
);

Batch tokenize

For ETL pipelines. Max 100 items per API request; the SDK auto-chunks larger lists.

use Iceberg\Subzero\Models\TokenizeBatchContext;
use Iceberg\Subzero\Models\TokenizeBatchItem;
use Iceberg\Subzero\Models\TokenizeBatchSource;

$results = $client->tokenizeBatch(
    [
        new TokenizeBatchItem(0, 'SSN', '123-45-6789'),
        new TokenizeBatchItem(1, 'SSN', '987-65-4321'),
    ],
    context: new TokenizeBatchContext(source: TokenizeBatchSource::Dbt, pipelineId: 'contacts'),
);

foreach ($results as $item) {
    if ($item->ok()) {
        echo "{$item->index}: {$item->token}\n";
    } else {
        echo "{$item->index} error: {$item->error}\n";
    }
}

Errors

The SDK throws typed exceptions from API reason codes — match on $exception->reason, not message text:

Example

With the API running and keys configured in the dashboard:

export SUBZERO_TOKENIZE_API_KEY=sz_live_...
export SUBZERO_REVEAL_API_KEY=sz_live_...
php examples/vault_demo.php

Tests

composer test

Related

• Python SDK
• Node SDK
• C# SDK
• Vault API