Skip to content
Akmelo

Documentation

PHP SDK: Browser: actions on a page

$ctx->browser()->open($url) returns $page. The examples below are individual actions on an already open page. Close it when finished, preferably in finally.

Complete SDK reference

Methods

goto

goto(string $url): BrowserPage

Navigate to another URL in the same browser page.

$page->goto($ctx->param('next_url'))->waitFor('.product-card');

Result and notes. Returns the same BrowserPage. Useful for pagination without taking another browser slot.

click

click(string $selector, int $timeoutMs = 5000): BrowserPage

Click the first element matching the selector.

$page->click('button.load-more', 5000);
$page->waitFor('.product-card');

Result and notes. Returns BrowserPage. timeoutMs is in milliseconds and defaults to 5000. Wait for new data after clicking; an old card still being present does not prove that the next page loaded.

type

type(string $selector, string $text): BrowserPage

Enter text in a matching field.

$page->type('input[name=search]', 'belt');
$page->click('button[type=submit]');

Result and notes. Returns BrowserPage. Typing alone may not submit a form; click its button separately if needed.

scroll

scroll(int $times = 1, int $delayMs = 500): BrowserPage

Scroll down in steps, with a pause between them.

$page->scroll(3, 700);

Result and notes. Returns BrowserPage. One call supports up to 20 steps. delayMs is the delay between steps. Check whether new products appeared after scrolling.

waitFor

waitFor(string $selector, int $timeoutMs = 10000): BrowserPage

Wait for an element matching the selector.

$page->waitFor('.product-card .price', 10000);

Result and notes. Returns BrowserPage. The default timeout is 10000 ms. An error occurs if the element does not appear; increasing the timeout indefinitely will not fix a wrong selector.

hover

hover(string $selector, int $timeoutMs = 5000): BrowserPage

Move the pointer over an element to open a menu or tooltip: $page->hover('.catalog-menu');.

scrollTo

scrollTo(string $selector, int $timeoutMs = 5000): BrowserPage

Scroll to a specific element: $page->scrollTo('.product-card');.

select

select(string $selector, string $value, int $timeoutMs = 5000): BrowserPage

Select a native dropdown value: $page->select('select.city', 'perm');.

press

press(string $selector, string $key, int $timeoutMs = 5000): BrowserPage

Press a key in an element: $page->press('input.search', 'Enter');.

content

content(): string

Get the current HTML after browser actions.

$html = $page->content();
$dom = $ctx->dom($html, $ctx->param('catalog_url'));

Result and notes. Returns an HTML string. Pass the current page URL to Dom, especially after goto().

screenshot

screenshot(): string

Save an image of the current page.

$uuid = $page->screenshot();
$ctx->log('Screenshot saved', ['snapshot_uuid' => $uuid]);

Result and notes. Returns a screenshot UUID, not PNG bytes or a public URL. Wait for the relevant element before capturing.

close

close(): void

Close the page and release its browser slot.

$page->close();

Result and notes. Returns nothing. A closed page cannot be used again. In production scripts, close it in finally.

captureResponses

captureResponses(array $patterns): BrowserPage

Start capturing XHR/fetch responses matching full URL patterns. At most 20 patterns, each up to 1024 characters. A new configuration clears the old buffer; [] disables capture. Past requests cannot be recovered. To capture the initial navigation, use the second argument of browser()->open().

$page->captureResponses(['*/api/products*', '*/graphql*']);
$page->click('button.load-more');
$response = $page->waitForResponse('*/api/products*');

waitForResponse

waitForResponse(string $pattern = '*', int $timeoutMs = 10000): ?array

Take the first completed matching response. This method checks the buffer before waiting, so a response received during open() or click() is retained. The response is removed from the buffer after reading. Returns null on timeout (0–30000 ms). HTTP error responses are returned too; inspect status yourself.

$response = $page->waitForResponse('*/api/products*', 10000);
if ($response !== null && $response['error'] === null && !$response['truncated']) {
    $data = $ctx->json($response['body']);
    $ctx->log('API response', ['status' => $response['status'], 'url' => $response['url']]);
}

A response has url, method, resource_type (xhr or fetch), status, headers, body, truncated, and error. body contains text, including JSON/XML. Set-Cookie headers are omitted. Binary bodies are unavailable (error=binary_body). For text exceeding 1 MiB, body is empty, truncated=true, and error=body_too_large. A failed body read gives error=body_unavailable. Do not feed an empty or incomplete body to the JSON parser.

responses

responses(): array

Take all completed responses and clear the buffer without waiting for requests still in progress. The result contains responses (a list), dropped (responses omitted because of limits), and pending (responses whose bodies are still being read).

$batch = $page->responses();
foreach ($batch['responses'] as $response) {
    $ctx->log('Network response', ['url' => $response['url'], 'status' => $response['status']]);
}
if ($batch['dropped'] > 0) {
    $ctx->abort('Buffer full: narrow the URL patterns and read responses more often');
}

Each page has its own buffer: up to 100 responses and 4 MiB, with at most 8 bodies being read simultaneously. Responses become available when their bodies finish reading, not in request start order. Closing the page destroys the buffer. Capture neither cancels nor retries requests. Do not publish response bodies containing personal data or secrets in logs.

solveCaptcha

solveCaptcha(array $hints = []): BrowserPage

Complete a supported challenge in the current page. Detection is normally automatic. Pass hints in the third argument of open() before navigation when the page requires manual configuration:

$page = $ctx->browser()->open((string) $ctx->param('catalog_url'), [], [
    'kind' => 'smartcaptcha',
    'success_selector' => '.product-card',
]);
try { $html = $page->content(); }
finally { $page->close(); }

After an interaction shows a new challenge, use $page->solveCaptcha(['success_selector' => '.loaded-products']). The success element must be absent before the challenge is completed. v3 needs the public sitekey and action if they cannot be detected. Image tasks can use image_selector, instructions_selector and submit_selector. Never enter a website's secret key here.

A separate challenge allowance applies; AI tokens are not used. Unsupported challenges, exhausted allowance or unconfirmed access stop execution. The same challenge is never submitted twice for payment. Source access rules still apply. Customer-hosted agents do not use the cloud allowance.

CAPTCHA usage reference

Complete CAPTCHA SDK and REST reference covers all hint fields, automatic defaults, explicit calls, session opt-out, result verification, agents, limits and failures. User guide and current prices explain setup and billing.

Object selection uses kind: "yandex_image"; automatic detection normally needs no hints. image_selector identifies only the task image, instructions_selector the selection order, and success_selector a result that appears after success. No target-domain list is needed. Unsupported variants fail instead of returning fabricated data. Do not repeatedly retry the same rejected task.

For yandex_text, answer_selector identifies the text answer input when it cannot be detected automatically. See the full hints contract in the CAPTCHA API reference.