README

A strongly-typed, modern PHP SDK for the Cloudflare Browser Rendering REST API. Built with amphp/http-client for performance and crell/serde for robust object serialization.

Features

• Full Coverage: Supports /content, /screenshot, /pdf, /scrape, /json, /snapshot, /links, and /markdown endpoints.
• Strong Typing: Uses Request DTOs and specific Response objects.
• AI Extraction: Seamless integration with spiral/json-schema-generator to extract structured data from webpages into PHP objects.
• Custom Exceptions: Granular error handling for API errors.

Installation

composer require shanginn/cloudflare-browser

Documentation

📚 View the full Wiki Documentation for detailed guides on all endpoints.

Quick Links

• Getting Started & REST API Overview
• Fetching HTML Content
• Capturing Screenshots
• Generating PDFs
• Taking Snapshots
• Scraping Elements
• AI Structured Data Extraction
• Retrieving Links
• Extracting Markdown

Basic Usage

Setup

use Shanginn\CloudflareBrowser\CloudflareClient;
use Shanginn\CloudflareBrowser\CloudflareBrowser;

$accountId = getenv('CLOUDFLARE_ACCOUNT_ID');
$apiToken = getenv('CLOUDFLARE_API_TOKEN');

$client = new CloudflareClient($accountId, $apiToken);
$browser = new CloudflareBrowser($client);

Take a Screenshot

use Shanginn\CloudflareBrowser\Requests\ScreenshotRequest;

$pngData = $browser->screenshot(new ScreenshotRequest(
    url: 'https://example.com',
    screenshotOptions: ['fullPage' => true]
));

file_put_contents('screenshot.png', $pngData);

See the Screenshot Documentation for more examples including:

• Custom HTML screenshots
• Authenticated pages
• Full-page captures
• Element-specific screenshots
• High-resolution captures

Scrape Elements

use Shanginn\CloudflareBrowser\Requests\ScrapeRequest;

$results = $browser->scrape(new ScrapeRequest(
    url: 'https://news.ycombinator.com',
    elements: [
        ['selector' => '.titleline > a']
    ]
));

foreach ($results as $group) {
    foreach ($group->results as $element) {
        echo "Found: {$element->text} ({$element->attributes['href'] ?? ''})\n";
    }
}

See the Scraping Documentation for more details.

Advanced Usage

AI Structured Data Extraction

Define your target data structure using a PHP class and attributes. The SDK will generate the JSON schema and map the AI response back to your object.

1. Define Schema:

use Spiral\JsonSchemaGenerator\Attribute\Field;

class ProductSchema 
{
    public function __construct(
        #[Field(title: 'Product Title', description: 'The main name of the item')]
        public string $title,

        #[Field(title: 'Price', description: 'Current price')]
        public float $price,
    ) {}
}

2. Extract:

use Shanginn\CloudflareBrowser\Requests\JsonRequest;

/** @var ProductSchema $product */
$product = $browser->json(
    new JsonRequest(
        url: 'https://example-shop.com/item/123', 
        prompt: 'Extract the main product details'
    ),
    ProductSchema::class
);

echo "Product: {$product->title} - \${$product->price}\n";

See the JSON Endpoint Documentation for more examples including array extraction and custom AI models.

Generating PDFs

use Shanginn\CloudflareBrowser\Requests\PdfRequest;
use Shanginn\CloudflareBrowser\Requests\Common\Viewport;

$pdfData = $browser->pdf(new PdfRequest(
    url: 'https://example.com',
    viewport: new Viewport(width: 1200, height: 800)
));

file_put_contents('page.pdf', $pdfData);

See the PDF Documentation for more examples including:

• Custom headers and footers
• Page format options (A4, A5, Letter, etc.)
• Blocking images/resources
• Dynamic placeholders (page numbers, dates, titles)

Fetch HTML Content

$html = $browser->content('https://example.com');
echo $html;

See the Content Documentation for handling JavaScript-heavy pages and blocking resources.

Extract Markdown

$markdown = $browser->markdown('https://example.com');
echo $markdown;

See the Markdown Documentation for more details.

Get All Links

$links = $browser->links('https://example.com');

// Or get only internal links
$internalLinks = $browser->links(
    url: 'https://example.com',
    excludeExternal: true
);

See the Links Documentation for more details.

Take a Snapshot

use Shanginn\CloudflareBrowser\Requests\SnapshotRequest;

$snapshot = $browser->snapshot(new SnapshotRequest(
    url: 'https://example.com'
));

echo "Title: " . $snapshot->title . "\n";
echo "Content: " . $snapshot->content . "\n";

See the Snapshot Documentation for more examples.

Authentication

Before you begin, make sure you create a custom API Token with the following permissions:

• Browser Rendering - Edit

Set these environment variables:

• CLOUDFLARE_ACCOUNT_ID - Your Cloudflare Account ID
• CLOUDFLARE_API_TOKEN - Your Cloudflare API Token

Monitoring Usage

You can monitor Browser Rendering usage in two ways:

• In the Cloudflare dashboard, go to the Browser Rendering page to view aggregate metrics. Go to Browser Rendering
• X-Browser-Ms-Used header: Returned in every REST API response, reporting browser time used for that request (in milliseconds).

Troubleshooting

If you have questions or encounter an error, see the Browser Rendering FAQ and troubleshooting guide.

License

MIT