К содержимому
Akmelo

Документация

PHP SDK: Браузер: действия на странице

$page возвращает $ctx->browser()->open($url). Примеры ниже являются отдельными действиями над уже открытой страницей. Завершайте работу через close, лучше в finally.

Общий справочник SDK

Методы

goto

goto(string $url): BrowserPage

Перейти на другой URL в той же браузерной странице.

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

Результат и особенности. Возвращает ту же BrowserPage. Удобно для пагинации без нового слота браузера.

click

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

Нажать на первый элемент по селектору.

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

Результат и особенности. Возвращает BrowserPage. timeoutMs в миллисекундах, по умолчанию 5000. После клика дождитесь именно новых данных; наличие старой карточки не доказывает загрузку следующей страницы.

type

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

Ввести текст в найденное поле.

$page->type('input[name=search]', 'ремень');
$page->click('button[type=submit]');

Результат и особенности. Возвращает BrowserPage. Сам ввод не обязан отправлять форму; при необходимости нажмите кнопку отдельно.

scroll

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

Прокрутить страницу вниз несколькими шагами с паузами.

$page->scroll(3, 700);

Результат и особенности. Возвращает BrowserPage. До 20 шагов за вызов; delayMs является задержкой между шагами. После прокрутки проверяйте, появились ли новые товары.

waitFor

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

Дождаться появления элемента по селектору.

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

Результат и особенности. Возвращает BrowserPage. timeoutMs по умолчанию 10000. Если элемент не появился, возникает ошибка; увеличивать тайм-аут бесконечно не стоит.

hover

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

Навести указатель, чтобы раскрыть меню или подсказку: $page->hover('.catalog-menu');.

scrollTo

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

Прокрутить страницу до конкретного элемента: $page->scrollTo('.product-card');.

select

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

Выбрать значение обычного списка: $page->select('select.city', 'perm');.

press

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

Нажать клавишу в элементе: $page->press('input.search', 'Enter');.

content

content(): string

Получить текущий HTML после действий браузера.

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

Результат и особенности. Возвращает строку HTML. Передавайте в Dom адрес текущей страницы, особенно после goto.

screenshot

screenshot(): string

Сохранить изображение текущей страницы.

$uuid = $page->screenshot();
$ctx->log('Сохранён снимок', ['snapshot_uuid' => $uuid]);

Результат и особенности. Возвращает UUID снимка, не байты PNG и не публичный URL. Перед снимком дождитесь нужного элемента.

close

close(): void

Закрыть страницу и освободить браузерный слот.

$page->close();

Результат и особенности. Ничего не возвращает. После закрытия страницу использовать нельзя. В рабочем коде закрывайте её в finally.

captureResponses

captureResponses(array $patterns): BrowserPage

Начать захват XHR/fetch по маскам полного URL. До 20 масок, до 1024 символов каждая. Новая настройка очищает старый буфер, [] отключает захват. Уже прошедшие запросы не восстанавливаются: для первого открытия используйте второй аргумент 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

Забрать первый готовый ответ по маске. Сначала проверяет буфер, затем ждёт: поэтому ответ, пришедший во время open() или click(), не теряется. Прочитанный ответ удаляется из буфера. Возвращает null при таймауте (0–30000 мс). Возвращает и ошибочные HTTP-статусы: проверяйте status самостоятельно.

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

Ответ содержит url, method, resource_type (xhr или fetch), status, headers, body, truncated и error. body содержит текст, включая JSON/XML. Заголовки Set-Cookie не выдаются. Бинарные тела не возвращаются (error=binary_body). Если текст больше 1 МиБ, body пустое, truncated=true, error=body_too_large; при невозможности чтения error=body_unavailable. Не передавайте пустое или неполное тело в JSON-парсер.

responses

responses(): array

Забрать все готовые ответы и очистить буфер, без ожидания запросов, которые ещё выполняются. Результат: responses (список ответов), dropped (число пропущенных из-за лимита), pending (число ответов, чьи тела ещё читаются).

$batch = $page->responses();
foreach ($batch['responses'] as $response) {
    $ctx->log('Сетевой ответ', ['url' => $response['url'], 'status' => $response['status']]);
}
if ($batch['dropped'] > 0) {
    $ctx->abort('Буфер переполнен: сузьте маски URL и читайте ответы чаще');
}

Буфер каждой страницы независим: до 100 ответов и 4 МиБ, не более 8 одновременно читаемых тел. Ответы доступны по завершении чтения тела, а не в порядке начала запросов. После закрытия страницы буфер уничтожается. Захват не отменяет и не повторяет запросы. Не публикуйте тела с персональными данными или секретами в журнале.

solveCaptcha

solveCaptcha(array $hints = []): BrowserPage

Пройти поддерживаемую проверку в текущей странице. Обычно она определяется автоматически. Если сайт устроен нестандартно, укажите параметры в настройках сайта или третьим аргументом open() до перехода. Например:

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

После действия, которое показало новую проверку, доступен $page->solveCaptcha(['success_selector' => '.loaded-products']). Указывайте элемент, которого нет до успешной загрузки. Для v3 нужны открытый sitekey и action, если они не определились автоматически. Для проверки с изображением можно указать image_selector, instructions_selector и submit_selector. Секретный ключ сайта сюда не вводится.

Решение расходует отдельную квоту проверок, не токены AI. При неизвестном типе, нехватке квоты или неподтверждённом доступе выполнение останавливается с ошибкой. Повторной платной отправки того же challenge нет. Правила доступа к источнику продолжают действовать. Время локального выполнения не расходует облачные вычисления, но количество и стоимость CAPTCHA учитываются отдельно у пространства агента.

Полный справочник CAPTCHA

SDK и REST API для CAPTCHA описывает все hints, значения по умолчанию, явный вызов, отключение, проверку результата, агенты, пределы и ошибки. Руководство пользователя и актуальные цены помогут настроить функцию и оплату.

Для выбора объектов используется kind: "yandex_image"; обычно тип определяется автоматически. image_selector указывает только картинку задания, instructions_selector порядок выбора, success_selector новый результат успешной операции. Список доменов целевых сайтов не нужен. Неизвестный вариант завершается ошибкой. Не запускайте бесконечные повторы при отказе.

Для yandex_text параметр answer_selector указывает поле текстового ответа, если оно не определилось автоматически. Полный контракт hints приведён в справочнике CAPTCHA API.