README

PHP SDK for the current SiteScreen public API.

Installation

composer require sitescreen/siterenderer:^2.2

The current SDK line targets api.sitescreen.io. It is not API-compatible with the earlier 1.x API.

The SDK targets the public SiteScreen HTTP API:

• GET /health
• GET /v1/me
• GET /v1/account
• GET /v1/render/presets
• POST /v1/screen
• POST /v1/screen/wait
• GET /v1/jobs/{jobId}
• GET /v1/reports/{jobId}
• POST /v1/render/url
• POST /v1/render/url/wait
• POST /v1/render/html
• POST /v1/render/html/wait
• GET /v1/render/jobs/{jobId}

Authentication uses only:

Authorization: Bearer <api_key>

X-Api-Key is not supported by the current API.

Target URLs and baseUrl values must use http or https, include a host, and must not contain URL credentials.

URL Policy Errors

The public API also rejects unsafe or non-actionable targets before queueing paid work: malformed URLs, placeholder/non-public TLDs, local/private IP addresses, non-public hostnames, and ports outside the SiteScreen allowlist. These failures are surfaced as ApiException with machine-readable apiCode values:

• invalid_url;
• unsupported_target;
• target_not_allowed.

use SiteScreen\SiteRenderer\DTO\ScreenUrlWaitRequest;
use SiteScreen\SiteRenderer\Exception\ApiException;

try {
    $client->screenUrlAndWait(new ScreenUrlWaitRequest(url: 'https://example.invalid'));
} catch (ApiException $e) {
    if ($e->isUrlPolicyViolation()) {
        echo $e->apiCode . ': ' . $e->getMessage() . PHP_EOL;
    }
}

Account and Billing

Use getAccount() to validate the API key and inspect current point balance, usage counters, pricing, and feature capabilities:

$account = $client->getAccount();

echo $account->apiKey->id . PHP_EOL;
echo $account->billing->balancePoints . ' ' . $account->billing->currency . PHP_EOL;
echo 'screen=' . $account->billing->pricing->screenPoints . PHP_EOL;
echo 'render=' . $account->billing->pricing->renderPoints . PHP_EOL;

The public API charges accepted screening and render requests in account points. If the key has insufficient balance, paid work fails with ApiException and HTTP status 402.

Screening

use SiteScreen\SiteRenderer\DTO\ScreenUrlWaitRequest;
use SiteScreen\SiteRenderer\DTO\ScreeningLimits;
use SiteScreen\SiteRenderer\SiteScreenClient;

$client = new SiteScreenClient(
    apiKey: getenv('SITESCREEN_API_KEY'),
    apiBaseUrl: 'https://api.sitescreen.io'
);

$result = $client->screenUrlAndWait(new ScreenUrlWaitRequest(
    url: 'https://example.com',
    profile: 'desktop-chromium',
    browser: true,
    screenshot: true,
    ai: true,
    limits: new ScreeningLimits(timeoutMs: 45_000, maxRedirects: 12, maxTextChars: 30_000),
    maxWaitMs: 180_000
));

$job = $result->completed ? $result->job : $client->getScreeningJob($result->jobId);
$report = $job?->report;

For async flow:

$accepted = $client->screenUrl(new ScreenUrlRequest(url: 'https://example.com'));
$job = $client->getScreeningJob($accepted->jobId);

Completed screening reports contain raw arrays for ruleVerdict, probe, browser, ai, and telemetry. Keeping the report raw is deliberate while the screening schema is still evolving.

The AI verdict is also available through typed helpers:

$ai = $job?->aiVerdict();
$classification = $job?->aiClassification();

echo $ai?->summary . PHP_EOL;
echo $classification?->siteType . PHP_EOL;
echo $classification?->primaryTopic . PHP_EOL;
echo $classification?->contentLanguage . PHP_EOL;

AiClassification exposes grouping-friendly axes such as accessState, siteType, primaryTopic, secondaryTopics, businessModel, audience, geoScope, contentLanguage, safetyRisk, sensitiveFlags, and normalizedTags.

Browser-side request guard telemetry is available through a typed helper:

$policy = $job?->browserSecurityPolicy();

foreach ($policy?->blockedRequests ?? [] as $blocked) {
    echo $blocked->url . ' -> ' . $blocked->reason . PHP_EOL;
}

URL Rendering

use SiteScreen\SiteRenderer\DTO\ContentType;
use SiteScreen\SiteRenderer\DTO\RenderLimits;
use SiteScreen\SiteRenderer\DTO\RenderMode;
use SiteScreen\SiteRenderer\DTO\RenderUrlWaitRequest;

$wait = $client->renderUrlAndWait(new RenderUrlWaitRequest(
    url: 'https://example.com',
    fullPage: true,
    profile: 'desktop-chromium',
    contentType: ContentType::PNG,
    renderMode: RenderMode::PAGE,
    limits: new RenderLimits(timeoutMs: 60_000, maxFullPageHeightPx: 20_000),
    maxWaitMs: 180_000
));

$job = $wait->completed ? $wait->job : $client->getRenderJob($wait->jobId);
$artifactUrl = $job?->result?->artifactUrl();

Supported URL render outputs in the current API version:

• viewport PNG: contentType=png, fullPage=false, renderMode=page;
• full-page PNG: contentType=png, fullPage=true, renderMode=page;
• full-page JPEG: contentType=jpg, fullPage=true, renderMode=page;
• page PDF: contentType=pdf, renderMode=page;
• document-style PDF: contentType=pdf, renderMode=document.

Document-style PDF supports header/footer templates, grayscale mode, text PDF mode, A4-oriented PDF options, and printer-like high-contrast background lightening.

Current document-mode limitations:

• DocumentPdfMode::IMAGE / pdf:image is intentionally exposed as a future SDK option but throws NotImplementedYetException until the API supports it.
• DocumentSignatureBlockOptions validates prepared PNG/JPEG data:image payloads, but using it in DocumentOptions throws NotImplementedYetException until signature/seal rendering is available in the API.

HTML Rendering

Raw HTML rendering uses the same render result schema and artifact handling as URL rendering. baseUrl is optional and is used by the browser layer to resolve relative CSS, image, font, and link URLs.

use SiteScreen\SiteRenderer\DTO\ContentType;
use SiteScreen\SiteRenderer\DTO\RenderHtmlWaitRequest;
use SiteScreen\SiteRenderer\DTO\RenderLimits;
use SiteScreen\SiteRenderer\DTO\RenderMode;

$wait = $client->renderHtmlAndWait(new RenderHtmlWaitRequest(
    html: '<!doctype html><html><body><h1>Invoice</h1></body></html>',
    fullPage: true,
    profile: 'desktop-chromium',
    contentType: ContentType::PNG,
    renderMode: RenderMode::PAGE,
    limits: new RenderLimits(timeoutMs: 60_000, maxFullPageHeightPx: 20_000),
    baseUrl: 'https://example.com/',
    maxWaitMs: 180_000
));

$job = $wait->completed ? $wait->job : $client->getRenderJob($wait->jobId);
$artifactUrl = $job?->result?->artifactUrl();

HTML input is currently limited by the public API to 2 MiB before JSON overhead. Larger HTML documents should be published as URLs or split into a future upload-based render flow.

Artifacts

Render results and screening screenshots usually expose a CDN-facing artifact alias:

$downloaded = $client->downloadFile($artifactUrl);
$downloaded->saveToPath(__DIR__ . '/output/' . $downloaded->fileName);

Artifact URLs have the form:

https://cdn.sitescreen.io/a/<type>/<id>.<ext>

Provider-specific object storage URLs are implementation details and should not be stored as the public artifact contract.

If remote artifact storage is unavailable and inline fallback is enabled, render results may contain artifactBase64 instead of artifact.url.

The /files/<name> endpoint is not part of the 2.x SDK surface. Pass the full artifact URL returned by the API.

Not Implemented Yet

The following SDK surface is intentionally present but throws NotImplementedYetException until the API supports it:

• document pdf:image rasterized PDF mode;
• document signature/seal block options.

Development

Do not run PHP or Composer directly on the host. Use a container:

docker run --rm -v "$PWD":/app -w /app composer:2 composer validate --no-check-publish
docker run --rm -v "$PWD":/app -w /app php:8.3-cli sh -lc 'find src tests -name "*.php" -print0 | xargs -0 -n1 php -l'

For the full dev check, install dependencies inside a temporary container copy so vendor/ and composer.lock are not written into the library repo:

docker run --rm -v "$PWD":/src -w /tmp composer:2 sh -lc 'mkdir -p /app && cp -a /src/. /app && cd /app && composer install && composer test && composer analyse'

License

The SiteScreen PHP SDK is released under the MIT License.