ScreenshotNeo

BlogHow-to

How to Generate a Web Page Snapshot or Thumbnail with PHP

Create reliable webpage snapshots in PHP with Chrome, Browsershot, or Playwright, then compare the setup with a one-call ScreenshotNeo API.

By the ScreenshotNeo team30 September 20267 min read

How to Generate a Web Page Snapshot or Thumbnail with PHP

Use a real browser engine to render the page, then save a deliberate viewport, element clip, or full-page capture. PHP libraries do not replace Chrome or Chromium: they control a browser that executes HTML, CSS, JavaScript, fonts, and images before producing the image.

For direct control, chrome-php/chrome exposes navigation, waiting, formats, clips, and full-page screenshots. Spatie Browsershot offers a higher-level URL or HTML API through Puppeteer and headless Chrome. Playwright PHP is useful when your project already uses Playwright-style browser automation.

Choose the output before choosing the library

Goal Capture Why
Fixed social or card thumbnail Set viewport width and height The result matches the slot where it will be displayed.
One chart, card, or section Element screenshot or clip Removes unrelated page content and keeps the subject readable.
Complete page record Full-page screenshot Includes content below the fold, but can be very tall and large.

A thumbnail is not automatically a full-page screenshot. Decide the target dimensions, crop behavior, and format first. PNG preserves sharp text, JPEG is smaller for photographic pages, and WebP is often a practical modern default when your consumers support it.

Choose a viewport, element clip, or full-page capture based on where the image will be used.
Choose a viewport, element clip, or full-page capture based on where the image will be used.

Option 1: chrome-php/chrome (direct PHP control)

The project README lists PHP 7.4–8.5 and Chrome or Chromium 65+ as requirements. Install the Composer package and ensure the browser executable exists on the deployment host.

composer require chrome-php/chrome

This complete example opens a URL, sets a thumbnail viewport, waits for navigation, and writes a WebP file. The finally block closes Chrome even when navigation or saving fails.

<?php

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

use HeadlessChromium\BrowserFactory;

$url = $argv[1] ?? 'https://example.com';
$output = __DIR__ . '/storage/example.webp';

$browserFactory = new BrowserFactory();
$browser = $browserFactory->createBrowser([
    // Set this when Chrome is not on PATH:
    // 'executablePath' => '/usr/bin/google-chrome',
    'headless' => true,
]);

try {
    $page = $browser->createPage();
    $page->setViewport(1200, 630);
    $page->navigate($url)->waitForNavigation();

    // WebP quality is supported by the library's screenshot options.
    $page->screenshot([
        'format' => 'webp',
        'quality' => 82,
    ])->saveToFile($output);
} finally {
    $browser->close();
}

echo "Saved {$output}\n";

Run it with php capture.php https://example.com. Create the output directory before saving, or use an absolute writable path.

PNG, JPEG, WebP, clips, and full page

// PNG (default in many examples)
$page->screenshot()->saveToFile('/tmp/page.png');

// JPEG with a quality value
$page->screenshot([
    'format' => 'jpeg',
    'quality' => 85,
])->saveToFile('/tmp/page.jpg');

// Capture a rectangular region (coordinates are CSS pixels)
$page->screenshot([
    'clip' => [
        'x' => 0,
        'y' => 0,
        'width' => 1200,
        'height' => 630,
        'scale' => 1,
    ],
])->saveToFile('/tmp/clip.png');

// Capture the entire document
$page->screenshot([
    'captureBeyondViewport' => true,
    'clip' => [
        'x' => 0,
        'y' => 0,
        'width' => 1200,
        'height' => 4000,
        'scale' => 1,
    ],
])->saveToFile('/tmp/full-page.png');

Use an element clip when you know the coordinates or obtain the element’s bounding box through the browser API. A full-page image can exceed downstream upload limits; resize or generate a viewport thumbnail when the destination expects a small card.

Option 2: Spatie Browsershot

Browsershot provides a shorter API for converting a URL or supplied HTML into an image or PDF. It runs Puppeteer with headless Chrome, so production still needs Node.js, Puppeteer, and a compatible browser installation.

composer require spatie/browsershot
npm install puppeteer
<?php

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

use Spatie\Browsershot\Browsershot;

Browsershot::url('https://example.com')
    ->windowSize(1200, 630)
    ->deviceScaleFactor(1)
    ->setScreenshotType('webp')
    ->save(__DIR__ . '/storage/example.webp');

// Supplied HTML is also supported:
Browsershot::html('<main><h1>Rendered HTML</h1></main>')
    ->windowSize(1200, 630)
    ->save(__DIR__ . '/storage/html.png');

Configure the Node and Chrome paths when your deployment does not use the defaults. Browsershot’s older v2 Chrome CLI route is no longer maintained; use the current Puppeteer-based setup.

Option 3: Playwright PHP

Playwright PHP is another route when browser automation or end-to-end testing is already part of your stack. The documented setup requires PHP 8.2 or newer and Node.js 20 or newer, plus the Playwright browser installation. Treat those as setup requirements for that route rather than as PHP-only dependencies.

composer require -W playwright-php/playwright
npx playwright install chromium

The API supports viewport screenshots, full-page screenshots, and element screenshots. Follow the package’s current installation instructions for the exact namespace and launch options, because these requirements and APIs can change between releases.

Wait for the page state you actually need

Waiting only for the initial response can capture an empty shell while JavaScript is still rendering. Pick a condition that represents the content you want:

  • Navigation complete: enough for static pages.
  • Selector present: wait for a chart, hero image, or app root.
  • Network idle: useful for client-rendered pages, but analytics or long polling can prevent it.
  • Explicit delay: a fallback for animations or third-party widgets; keep it bounded.

For lazy-loaded images, scroll or use the library’s full-page behavior so content below the fold is requested before capture. Disable animations with injected CSS when deterministic pixels matter:

<style>*, *::before, *::after {
  animation-duration: 0s !important;
  animation-delay: 0s !important;
  transition: none !important;
}</style>

Authentication, headers, and private pages

Set cookies, HTTP headers, or an authenticated session before navigation. Never place long-lived secrets in a public URL or commit them to source control. A production worker should load credentials from its secret store, limit the target host, and remove temporary cookies after the job.

Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF, while its capture flow accepts consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status.

Consent banners and overlays can change the pixels unless they are handled before capture.
Consent banners and overlays can change the pixels unless they are handled before capture.

Read the parameter list and response details in the ScreenshotNeo documentation.

PHP

<?php

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

use GuzzleHttp\Client;

$client = new Client(['timeout' => 90]);
$response = $client->get('https://api.screenshotneo.com/v1/shot', [
    'query' => [
        'access_key' => getenv('SCREENSHOTNEO_API_KEY'),
        'url' => 'https://stripe.com',
    ],
]);

file_put_contents(__DIR__ . '/stripe.webp', $response->getBody()->getContents());

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

You can also use full-page capture with lazy images loaded, CSS element capture, dark mode, device presets, retina scale, custom CSS and JavaScript, clicks, selector waits, request blocking, cookies, headers, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, cache TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, and the usage API. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.

There are 1,000 free shots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free, and every feature is included on every plan. Create a free ScreenshotNeo account.

Troubleshooting

Symptom Likely cause Fix
Chrome executable not found Browser is absent or not on PATH. Install Chrome/Chromium in the image and configure its executable path.
Blank or half-rendered image Capture happened before client rendering finished. Wait for a meaningful selector, network idle, or a bounded delay.
Missing images Lazy loading, blocked requests, or failed remote assets. Scroll/full-page capture, allow required hosts, and inspect browser logs.
Cookie banner covers content The site requires consent before showing the page. Automate consent and hide the banner, or use ScreenshotNeo’s consent handling.
Output is enormous Full-page capture or a high device scale factor. Use a fixed viewport, element clip, lower scale, or resize after capture.
Works locally but fails in production Different browser, fonts, sandbox, permissions, or network policy. Pin the browser image, install fonts, check writable directories, and verify outbound access.
Timeout on network idle Analytics or long polling never becomes idle. Wait for a selector or use a maximum delay instead.

Performance, reliability, and cost

  • Reuse a browser process where your worker model permits it, while creating a fresh page for each job.
  • Set explicit navigation and overall job timeouts so one target cannot occupy a worker indefinitely.
  • Use JPEG or WebP for photographic pages and PNG for diagrams or text-heavy images.
  • Cache stable URLs and invalidate when the page changes; avoid caching personalized or authenticated content.
  • Record the URL, viewport, browser version, wait condition, output format, and failure reason for reproducibility.
  • For serverless deployments, include the browser binary and fonts in the image and account for cold-start cost.
  • With ScreenshotNeo, cache hits and failed or unusable page verdicts are not billed, and the X-Page-Verdict and X-Billed headers let a worker decide whether to retry.

FAQ

Can PHP create a screenshot without Chrome?

Not for a modern, JavaScript-rendered page. The PHP package controls a browser engine; it does not itself implement the web platform.

Should a thumbnail be full page?

Usually no. Use a deliberate viewport or element clip for a fixed card. Reserve full-page captures for archives and references.

Which PHP option should I start with?

Choose chrome-php/chrome for direct browser control, Browsershot for a concise URL or HTML conversion API, and Playwright PHP when its automation stack already fits your project.

How do I capture many URLs?

Use a queue with bounded concurrency and retries. ScreenshotNeo also supports bulk capture for up to 100 URLs per call and signed asynchronous webhooks.