PHP SDK: Context: запуск, данные и прогресс
Главный объект $ctx приходит в функцию run. Через него доступны остальные части SDK. Ниже показаны фрагменты для тела этой функции.
Методы
http()state()storage()browser()captcha()wildberries()ai()dom()json()text()url()emit()flush()log()progress()metric()param()params()credential()sleep()cancelled()abort()fail()now()
http
http(): HttpClient
Получить клиент для запросов к сайту. Все запросы используют сетевые настройки текущего сайта.
$http = $ctx->http();
$response = $http->get($ctx->param('catalog_url'));
Результат и особенности. Возвращает HttpClient. Сам вызов http() ещё ничего не загружает.
state
state(): KeyValue
Получить хранилище небольшого состояния обхода. Подходит для номера последней обработанной страницы.
$state = $ctx->state();
$page = (int) $state->get('page', 1);
Результат и особенности. Возвращает KeyValue. Это состояние прогона, а не общая база товаров.
storage
storage(string $code): Storage
Выбрать файловое S3-хранилище по коду подключения. Подключение нужно заранее настроить и разрешить для сайта.
$storage = $ctx->storage('media');
$exists = $storage->exists('catalog/report.json');
Результат и особенности. Возвращает Storage. media здесь является кодом подключения, а не адресом бакета.
browser
browser(): Browser
Получить браузер для страниц, которым нужен JavaScript, клики или прокрутка.
$browser = $ctx->browser();
$page = $browser->open($ctx->param('catalog_url'));
$page->close();
Результат и особенности. Возвращает Browser. Одновременно можно держать не более двух страниц.
wildberries
wildberries(): Wildberries
Получить готовый источник карточек для сайта, созданного из решения Wildberries. Список товаров и регионов берётся из настроек сайта. Все методы и пример.
$source = $ctx->wildberries();
$regions = $source->regions();
ai
ai(): Ai
Получить помощник для анализа содержимого, преобразования записей, поиска элемента и предложения исправления PHP-алгоритма. Каждый вызов AI расходует бюджет пространства. Методы, лимиты и примеры.
$result = $ctx->ai()->transform(['cost' => '1 250 ₽'], ['price_rub' => 0]);
yandexMarket
$source = $ctx->yandexMarket();
Получить товары и поисковую выдачу Яндекс Маркета для настроенного сценария. YandexMarket.
$source = $ctx->yandexMarket();
dom
dom(string $html, ?string $baseUrl = null): Dom
Разобрать уже полученный HTML. baseUrl нужен для преобразования относительных ссылок в полные.
$dom = $ctx->dom('<a href="/product/1">Товар</a>', 'https://shop.example.invalid/catalog');
$url = $dom->q('a')?->abs();
Результат и особенности. Возвращает Dom. Этот метод сам не делает запрос к сайту.
json
json(string $text, int $depth = 64): array
Разобрать JSON-текст в массив. depth ограничивает глубину вложенности.
$data = $ctx->json('{"items":[{"sku":"A-1"}]}');
$sku = $data['items'][0]['sku'];
Результат и особенности. Возвращает массив. При ошибочном JSON возникает JsonException. Корневое значение должно быть объектом или массивом, не строкой или числом.
text
text(): TextTools
Получить помощник для очистки текста, цен и артикулов.
$price = $ctx->text()->money('1 250,50 ₽');
Результат и особенности. Возвращает TextTools; в примере price = 1250.5.
url
url(): UrlTools
Получить помощник для ссылок, query-параметров и шаблонов страниц.
$url = $ctx->url()->withParam('https://shop.example.invalid/catalog', 'page', 2);
Результат и особенности. Возвращает UrlTools. В примере к адресу добавляется ?page=2.
emit
emit(array $item, ?string $key = null): void
Передать одну собранную запись системе. Поля должны соответствовать схеме сайта. key задаёт стабильный ключ товара.
$ctx->emit(['sku' => 'A-1', 'name' => 'Ремень', 'price' => 1250.5], 'A-1');
Результат и особенности. Ничего не возвращает. Запись проходит проверку и дедупликацию; emit не означает, что она уже сохранена в БД. Ключ должен оставаться одинаковым между прогонами.
flush
flush(): void
Отправить накопленную пачку записей, не дожидаясь автоматической отправки.
$ctx->emit(['sku' => 'A-1'], 'A-1');
$ctx->flush();
$ctx->log('Пачка передана');
Результат и особенности. Ничего не возвращает. Автоматическая отправка происходит при 100 записях или при очередном emit после двух секунд. При долгой паузе можно вызвать flush явно.
log
log(string $message, array $context = [], string $level = 'info'): void
Записать понятное сообщение в журнал прогона. Дополнительные значения передаются массивом context.
$ctx->log('Страница обработана', ['page' => 2, 'items' => 24], 'info');
Результат и особенности. Ничего не возвращает. Для замечаний используйте warning, для ошибки error. Не записывайте пароли, ключи и полные ответы сайта.
progress
progress(int $done, ?int $total = null, ?string $label = null, ?float $percent = null): void
Показать выполненную часть работы и название пользовательского этапа. total можно не знать заранее.
$ctx->progress(10, 50, 'Читаем карточки');
// Когда общий размер неизвестен:
$ctx->progress(3, null, 'Ищем категории');
Результат и особенности. 10 из 50 означает 20%. Четвёртый аргумент percent позволяет явно передать общий процент 0–100. Завершение этапа не заменяет конечный статус прогона.
metric
metric(string $name, float $value = 1): void
Добавить числовую метрику выполнения, например количество пропущенных карточек.
$ctx->metric('products_without_price', 1);
Результат и особенности. Ничего не возвращает. value по умолчанию 1. Для сообщений человеку используйте log, для видимого этапа progress.
param
param(string $name, mixed $default = null): mixed
Получить один параметр запуска. default используется, если параметра нет или его значение null.
$maxPages = (int) $ctx->param('max_pages', 20);
Результат и особенности. Возвращает значение любого типа. Проверяйте тип и допустимый диапазон перед использованием.
params
params(): array
Получить сразу все параметры запуска.
$params = $ctx->params();
$ctx->log('Есть настройки', ['count' => count($params)]);
Результат и особенности. Возвращает массив. Не выводите его целиком, если параметры содержат чувствительные значения.
credential
credential(string $name): string
Получить именованный секрет для доступа к целевому сайту. Имя должно соответствовать настроенному ключу.
$token = $ctx->credential('catalog_api');
$http = $ctx->http()->withHeaders(['Authorization' => 'Bearer ' . $token]);
Результат и особенности. Возвращает строку. Не передавайте секрет в emit и не публикуйте его в выгрузке.
sleep
sleep(int $ms): void
Сделать контролируемую паузу. Аргумент измеряется в миллисекундах.
$ctx->sleep(500);
Результат и особенности. Пауза на полсекунды. Время учитывается в выполнении; отмена прогона остаётся доступной.
cancelled
cancelled(): bool
Узнать, запросил ли пользователь остановку. Проверяйте в длительных циклах.
if ($ctx->cancelled()) {
return;
}
Результат и особенности. Возвращает true или false. При true прекратите выдавать новые запросы и корректно завершите работу.
abort
abort(string $reason): never
Остановить выполнение с объяснением причины, сохранив состояние для возможного продолжения. Прогон получает статус остановленного. Если источник ответил ошибкой или сломался формат данных, используйте fail().
if ($ctx->cancelled()) {
$ctx->abort('Сбор остановлен по запросу пользователя');
}
Результат и особенности. Не возвращается к следующей строке. Перед остановкой отправляет буфер emit. Не используйте abort как обычное успешное завершение.
fail
fail(string $reason): never
Завершить прогон с ошибкой, когда источник недоступен или ответ не соответствует ожидаемому формату. В отличие от abort(), такая остановка отмечается как ошибка, а не отмена.
if (! $response->ok()) {
$ctx->fail('Источник ответил HTTP '.$response->status);
}
Результат и особенности. Буфер emit() отправляется перед завершением. Если часть записей уже собрана, она сохраняется.
now
now(): \DateTimeImmutable
Получить текущую дату и время в UTC.
$stamp = $ctx->now()->format('Y-m-d\TH:i:s\Z');
Результат и особенности. Возвращает DateTimeImmutable. Для человекочитаемого времени учитывайте нужный часовой пояс отдельно.
mail(): Mail
Проверенное письмо текущего автоматического прогона. В пробном запуске содержимое настоящих писем недоступно.
$mail = $ctx->mail();
if ($mail->available()) $ctx->log($mail->current()['subject']);
Подробнее: почта и вложения.
documents
documents(): Documents
Получить обработчик текстов и таблиц Excel, PDF и Word.
$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$rows = $document->rows();
Подробнее: чтение документов.
sources
$ctx->sources() читает закреплённые входы ежедневного процесса. Запуск получает доступ только к источникам своего пространства, доступным инициатору. Обычный ручной прогон не получает доступ к произвольным письмам.
$catalog = $ctx->sources()->input('catalog');
captcha
captcha(): Captcha
Возвращает API явных заданий. Каталог и оценка цены не создают платное задание. Создание, получение статуса и обратная связь работают через учёт пространства в облаке и на агенте.