PHP SDK

The official PHP SDK for the Screenshot Scout screenshot API. It is distributed on Packagist as screenshotscout/sdk and developed in the screenshotscout-php repository.

Sign up for Screenshot Scout or sign in. We automatically create a default API key for you when you sign up. Open the API Keys page, copy the access key and secret key, and store them in a safe place.

Capture a screenshot

Create a client with your access key and call capture() with the URL of the page you would like to take a screenshot of:

<?php

declare(strict_types=1);

use ScreenshotScout\BinaryCaptureResponse;
use ScreenshotScout\CaptureOptions;
use ScreenshotScout\Client;

require __DIR__ . '/vendor/autoload.php';

$client = new Client(accessKey: 'YOUR_ACCESS_KEY');

$response = $client->capture(
    'https://example.com',
    (new CaptureOptions())->withFullPage(true),
);

if (!$response instanceof BinaryCaptureResponse) {
    throw new RuntimeException('Expected a binary response.');
}

file_put_contents('screenshot.png', $response->bytes());
echo ($response->screenshotUrl() ?? 'No screenshot URL returned') . PHP_EOL;

capture() sends a POST request by default. The withResponseType() option on CaptureOptions selects the response format. When you leave it unset, the call returns a BinaryCaptureResponse: the image data is in bytes(), and the exact screenshot URL is in screenshotUrl() when available.

Request a JSON result

Set the response type to CaptureResponseType::JSON to receive a JSON object with the screenshot URL instead of the image bytes:

<?php

declare(strict_types=1);

use ScreenshotScout\CaptureOptions;
use ScreenshotScout\CaptureResponseType;
use ScreenshotScout\Client;
use ScreenshotScout\JsonCaptureResponse;

require __DIR__ . '/vendor/autoload.php';

$client = new Client(accessKey: 'YOUR_ACCESS_KEY');

$response = $client->capture(
    'https://example.com',
    (new CaptureOptions())->withResponseType(CaptureResponseType::JSON),
);

if (!$response instanceof JsonCaptureResponse) {
    throw new RuntimeException('Expected a JSON response.');
}

echo ($response->result()->screenshotUrl() ?? 'No screenshot URL returned') . PHP_EOL;

The parsed JSON body is in result().

Set capture options

CaptureOptions is immutable: each with...() method returns a changed copy. It covers every option in the screenshot option reference through camelCase with...() methods: full_page becomes withFullPage(), block_cookie_banners becomes withBlockCookieBanners(), and so on. Options with a fixed set of documented values have constants, such as CaptureFormat::WEBP and CaptureResponseType::JSON; the methods also accept plain strings.

Build a capture URL

buildCaptureUrl() creates a capture URL without making an API request, for cases where another application or an HTML <img> element loads the screenshot directly:

<?php

declare(strict_types=1);

use ScreenshotScout\CaptureOptions;
use ScreenshotScout\Client;

require __DIR__ . '/vendor/autoload.php';

$client = new Client(accessKey: 'YOUR_ACCESS_KEY');

$captureUrl = $client->buildCaptureUrl(
    'https://example.com',
    (new CaptureOptions())
        ->withFullPage(true)
        ->withBlockAds(true),
);

echo $captureUrl . PHP_EOL;

The generated URL contains the access key. When a secret key is configured (see Signed requests), the SDK signs the URL automatically; otherwise it is unsigned. Treat generated URLs as sensitive. Before exposing one to browsers or users, configure a secret key and enable Require signed requests on the API Keys page.

Signed requests

Pass the API key's secret key as the secretKey constructor argument:

<?php

declare(strict_types=1);

use ScreenshotScout\Client;

require __DIR__ . '/vendor/autoload.php';

$client = new Client(
    accessKey: 'YOUR_ACCESS_KEY',
    secretKey: 'YOUR_SECRET_KEY',
);

The secret is used locally and is never transmitted. The client signs capture requests and generated capture URLs automatically. See the signed requests guide for details.

Errors

When the API returns a non-2xx response, the SDK throws ApiException, with the machine-readable error code in errorCode() and the descriptive message in errorMessage(). Every SDK exception implements the ScreenshotScoutException interface, so one catch block can handle any SDK error. The repository README documents all exception types.

Full reference

This page covers installation and your first captures. For everything else, see:

The repository README: GET requests, HTTP timeouts and a custom PSR-18 client, raw responses, and all exception types.
The standalone examples in the repository.
The screenshot option reference: service behavior and allowed values for every option.