Download the PHP package webscraping-ai/webscraping-ai-php without Composer

WebScraping.AI PHP Client

Official PHP client for the WebScraping.AI API.

The API gives you LLM-powered scraping tools with Chromium JavaScript rendering, rotating proxies, and built-in HTML parsing — full HTML, visible text, selected page areas, AI-extracted fields, and free-form question answering over any URL.

Requirements

• PHP 8.2 or newer
• A PSR-18 HTTP client — Guzzle, Symfony HttpClient, or any other implementation
• A PSR-17 message factory

If you don't already have these installed, the simplest pair is:

php-http/discovery (a transitive dependency) will pick them up automatically.

Installation

Quick start

Sign up to get an API key — a free trial, no credit card required. Your key lives in the dashboard.

All optional parameters (headers, timeout, js, js_timeout, wait_for, proxy, country, custom_proxy, device, error_on_404, error_on_redirect, js_script, …) are PHP named arguments. See the API docs for the full parameter reference.

Search engine results (SERP)

serp() returns parsed Google results for a query. It is query-shaped rather than URL-shaped, so none of the page-scraping parameters above apply — only q (required), engine ("google", the default), gl (country, default "us"), hl (language, default "en") and page (1–100, 10 results per page; the server rejects values above 100 with a 400). Priced per search (see pricing); failed searches are not charged.

The client validates before sending: an empty or whitespace-only q, or a page below 1, throws \InvalidArgumentException and no request (or charge) is made. The server also rejects a bad page with a 400 (not billed); checking client-side saves the round trip.

The decoded array has search_parameters, search_information, organic_results (position, title, link, domain, displayed_link, and optionally snippet / date), related_searches (optional) and pagination. Optional keys are omitted rather than set to null.

Structured data for supported sites

data() returns structured JSON for a public page on a supported site — pass the page's normal URL, e.g. a YouTube video/channel/playlist, TikTok video/profile, X (Twitter) post/profile, LinkedIn company/job/profile, Instagram post/reel/profile or Reddit post/subreddit/user. The site (provider) and page kind (type) are detected from the URL. Priced per site (see pricing), including results that parse empty or no longer exist; unsupported URLs and failed fetches are not charged.

More sites and page types are added on the server over time and work without upgrading this package, so the client does not check which sites are supported — only that url is non-blank (a blank url throws \InvalidArgumentException before any request). An unsupported URL or page type returns a 400 that is not charged (BadRequestException). Its message lists what is supported. For other sites use fields().

None of the page-scraping parameters (js, proxy, headers, timeout, …) apply. The options are:

• country — two-letter country code of the proxy used to fetch the page, us by default. The server rejects unknown codes with a 400.
• transcript — YouTube videos only. Also fetch the video's transcript into data.transcript. It's null when no matching captions are available. If the transcript fetch itself fails, the whole request fails with a 500 and is not charged.
• transcriptLanguage — caption language to pick, e.g. en or de. Without it, English is preferred, then the first available track. If the video has no captions in that language, data.transcript is null.

The decoded array has request_parameters (url, provider, type), parse_status and data. provider and type are open sets — expect new values. parse_status is ok, parse_failed (fetched but not parsed; data may be null or partial) or not_found; all three are charged successes. The shape of data depends on provider and type.

Provider-specific parameters added server-side after this release can be sent through params, as-is (scalar values; null is dropped). api_key, url, country, transcript and transcript_language are rejected with \InvalidArgumentException — use the named arguments for those, even when you haven't set them:

Bring your own HTTP client

By default, the client builds its own transport. If Guzzle is installed it is used with a request deadline applied (see Timeouts); otherwise php-http/discovery resolves whatever PSR-18 client is installed. To pin a specific client, pass it explicitly:

Injecting your own client opts out of the default deadline — configure transport-level timeouts on the client you pass.

Timeouts

Two different timeouts are in play, and they're easy to confuse:

• The timeout parameter accepted by each endpoint method (html(), text(), …) controls server-side page retrieval — how long the API waits for the target page. It does not bound how long your HTTP client waits.
• The transport timeout bounds how long the PSR-18 client itself will wait on TCP connect and on reading the response body, so a stalled connection can't hang your process forever.

By default the client applies a transport deadline when it builds its own client and Guzzle is available: a total request timeout of Client::DEFAULT_TIMEOUT (60s) and a TCP connect timeout of Client::DEFAULT_CONNECT_TIMEOUT (10s). Override them via the constructor:

These constructor timeouts apply only to the auto-built default client. If you inject your own httpClient, or no concrete client (Guzzle) is available and discovery falls back to an unknown PSR-18 implementation, no deadline is imposed — in that case inject a client with timeouts configured to get one.

Errors

The client raises typed exceptions for every documented status code:

All inherit from WebScrapingAI\Exception\ApiException, which exposes $message, $status, $statusCode, $statusMessage, $body, and $responseBody. The latter three are populated when the API surfaces target-page errors as 500s.

Transport-level failures raise WebScrapingAI\Exception\ApiTimeoutException (the PSR-18 client timed out) or WebScrapingAI\Exception\ApiConnectionException (DNS / connection refused / TLS).

All SDK-originated exceptions implement the marker interface WebScrapingAI\Exception\WebScrapingAIException, so a single catch (WebScrapingAIException $e) block catches everything.

Response shapes

The client returns whatever the API returns — it does not normalise or unwrap. A couple of current quirks worth knowing:

• fields() returns ['result' => [...fields...]] (the live API wraps the extracted fields under a result key).
• selectedMultiple() returns array<int, array<int, string>> — an outer wrapper containing all matched chunks concatenated.

These are upstream spec/server drifts; the official Ruby and Python clients return the same shapes.

Migration from 3.x

3.x was generated from the OpenAPI spec under the namespace OpenAPI\Client\ and used per-tag classes (AIApi, HTMLApi, etc.). 4.0 is a hand-authored rewrite with a single WebScrapingAI\Client entry point. There are no deprecation shims — pin to ^3.2 if you need the old surface.

Development

Links

• WebScraping.AI — features, pricing, signup
• API documentation
• Dashboard — API key, usage, request builder
• Other official clients: Python · JavaScript · Ruby · Go · Java · .NET · CLI · MCP server · n8n node
• Support: [email protected]

License

MIT — see LICENSE.