Привет, dev.to! Сегодня мы погрузимся в мир программного доступа к поисковым технологиям Яндекса. Если вы когда-либо хотели интегрировать поиск Яндекса в свое PHP-приложение, создать кастомную поисковую выдачу, анализировать тренды с помощью Wordstat или даже использовать генеративные возможности YandexGPT, то эта статья для вас.
Речь пойдет о библиотеке yandex-search-php, которая представляет собой мощный и удобный SDK для работы с Yandex Search API. Мы разберем, почему стоит использовать именно эту библиотеку, как ее установить и какие возможности она открывает.
Зачем нужен SDK, если есть API?
Yandex Search API — это мощный инструмент, но работа с ним напрямую через HTTP-запросы может быть сопряжена с рядом рутинных задач:
- Аутентификация: API требует использования IAM-токенов, которые нужно получать, используя OAuth-токен, и своевременно обновлять. Это лишний слой логики, который приходится реализовывать и поддерживать.
- Обработка ответов: API возвращает данные в формате JSON. Для удобной и безопасной работы в коде эти данные нужно преобразовывать в объекты (DTO), что требует написания дополнительного кода.
- Интеграция с фреймворками: При использовании фреймворков, таких как Laravel, хочется иметь готовую интеграцию: сервис-провайдеры, фасады, автоматическое внедрение зависимостей.
Библиотека yandex-search-php элегантно решает все эти проблемы, предоставляя разработчику чистый и интуитивно понятный интерфейс для взаимодействия с API.
Ключевые возможности yandex-search-php
Пакет предоставляет доступ ко всем основным функциям Yandex Search API:
- Классический веб-поиск: Полнотекстовый поиск по интернету с возможностью тонкой настройки (сортировка, группировка, фильтрация, регион).
- Генеративный поиск (YandexGPT): Возможность задавать вопросы и получать осмысленные ответы, сгенерированные нейросетью на основе реальных данных из поисковой выдачи.
- Поиск изображений: Поиск картинок по текстовому описанию и обратный поиск по изображению (по URL или загруженному файлу).
- Аналитика Wordstat: Программный доступ к данным Яндекс.Вордстат для анализа популярности ключевых слов, их динамики и распределения по регионам.
- Асинхронные операции: Возможность запускать долгие поисковые запросы и получать результат позже, не блокируя основной процесс.
- Типобезопасные DTO: Все ответы API типизированы и представлены в виде удобных объектов, что исключает ошибки при работе с данными.
- Готовая интеграция с Laravel: Пакет "из коробки" поддерживает Laravel 8-12, предоставляя фасад, сервис-провайдер и возможность внедрения зависимостей.
Начало работы
Требования
- PHP 8.0+
- Аккаунт в Yandex Cloud с подключенным Search API.
- OAuth-токен, который можно получить на oauth.yandex.ru.
Установка
Установка производится стандартно через Composer:
composer require tigusigalpa/yandex-search-php
Быстрый старт (Plain PHP)
Для использования в обычном PHP-проекте достаточно всего нескольких строк кода:
<?php
require_once 'vendor/autoload.php';
use Tigusigalpa\YandexCloudClient\YandexCloudClient;
use Tigusigalpa\YandexSearch\YandexSearchClient;
// 1. Создаем клиент Yandex Cloud с вашим OAuth-токеном
$cloudClient = new YandexCloudClient('ВАШ_OAUTH_ТОКЕН');
// 2. Создаем клиент Yandex Search, передавая клиент облака и ID вашего каталога
$searchClient = new YandexSearchClient($cloudClient, 'ВАШ_FOLDER_ID');
// 3. Выполняем поисковый запрос
$results = $searchClient->web()->search('Статья о PHP на dev.to');
echo "Найдено: {$results->found} результатов\n";
foreach ($results->documents as $doc) {
echo "- {$doc->title} ({$doc->url})\n";
}
Как видите, никакой магии с IAM-токенами. Библиотека берет всю работу по аутентификации на себя.
Быстрый старт (Laravel)
В Laravel все еще проще.
-
Публикуем конфигурационный файл:
php artisan vendor:publish --tag=yandex-search-config -
Добавляем учетные данные в
.env:
YANDEX_OAUTH_TOKEN=ваш_oauth_токен YANDEX_FOLDER_ID=ваш_folder_id -
Используем фасад или внедрение зависимостей:
use Tigusigalpa\YandexSearch\Laravel\Facades\YandexSearch; // Через фасад $results = YandexSearch::web()->search('Лучшие практики Laravel'); // Или через внедрение зависимости в контроллере public function __construct(private \Tigusigalpa\YandexSearch\YandexSearchClient $searchClient) { // ... } public function search(string $query) { $results = $this->searchClient->web()->search($query); return view('search_results', compact('results')); }
Углубляемся в возможности
Рассмотрим подробнее, как работать с основными модулями библиотеки.
Веб-поиск (web())
Это основной модуль для текстового поиска. Метод search() принимает поисковый запрос и опциональный массив параметров для тонкой настройки.
$results = $searchClient->web()->search('Новости PHP 8.3', [
'sortSpec' => [
'sortMode' => 'SORT_MODE_BY_TIME', // Сортировка по времени
'sortOrder' => 'SORT_ORDER_DESC' // От новых к старым
],
'region' => 225, // Россия
'page' => 0, // Первая страница результатов
]);
// Результат - это объект SearchResultDTO
echo "Найдено (в числовом формате): {$results->found}\n";
echo "Найдено (в читаемом формате): {$results->foundHuman}\n";
// $results->documents - это коллекция объектов SearchDocumentDTO
foreach ($results->documents as $doc) {
echo "\nЗаголовок: {$doc->title}\n";
echo "URL: {$doc->url}\n";
echo "Домен: {$doc->domain}\n";
echo "Отрывок: {$doc->passage}\n";
}
Генеративный поиск (gen())
Самая интересная часть — интеграция с YandexGPT. Вы можете задать вопрос и получить связный текстовый ответ, основанный на результатах поиска. Это открывает огромные возможности для создания чат-ботов, ассистентов и систем Q&A.
$response = $searchClient->gen()->search([
['role' => 'ROLE_USER', 'content' => 'В чем ключевые отличия PHP 8.2 от 8.3?']
]);
// Ответ - это объект GenerativeSearchResponseDTO
echo "Ответ ИИ:\n{$response->answer}\n";
echo "\nИсточники, использованные для ответа:\n";
foreach ($response->sources as $source) {
if ($source->used) {
echo "- {$source->title} ({$source->url})\n";
}
}
Библиотека также поддерживает многоходовые диалоги, позволяя создавать более сложные сценарии взаимодействия с ИИ.
Поиск изображений (images())
Модуль позволяет искать картинки по текстовому запросу или выполнять обратный поиск.
Поиск по тексту с фильтрами:
$results = $searchClient->images()->search('закат в горах', [
'imageSpec' => [
'size' => 'IMAGE_SIZE_LARGE', // Только большие изображения
'orientation' => 'IMAGE_ORIENTATION_HORIZONTAL', // Горизонтальные
'color' => 'IMAGE_COLOR_ORANGE' // С преобладанием оранжевого цвета
]
]);
// Результат - объект ImageSearchResultDTO
foreach ($results->images as $image) {
echo "- {$image->url} ({$image->width}x{$image->height})\n";
}
Обратный поиск по URL:
$results = $searchClient->images()->searchByImage([
'url' => 'https://example.com/my-cat.jpg'
]);
Аналитика Wordstat (wordstat())
Программный доступ к Яндекс.Вордстат — мечта любого SEO-специалиста или маркетолога. Библиотека делает эту мечту реальностью.
Получение топа связанных фраз:
$top = $searchClient->wordstat()->getTop('купить слона', [
'regions' => [213] // Москва
]);
foreach ($top->topPhrases as $phrase) {
echo "- {$phrase['phrase']}: {$phrase['count']} запросов\n";
}
Получение динамики популярности запроса:
$dynamics = $searchClient->wordstat()->getDynamics('Laravel');
foreach ($dynamics->dynamics as $period) {
echo "{$period['date']}: {$period['count']} запросов\n";
}
Заключение
Библиотека yandex-search-php — это высококачественный, хорошо документированный и удобный инструмент для любого PHP-разработчика, желающего работать с поисковыми технологиями Яндекса. Она абстрагирует от сложностей аутентификации, предоставляет удобные DTO для работы с результатами и отлично интегрируется с современными фреймворками, такими как Laravel.
Будь то добавление поиска по сайту, создание умного ассистента на базе YandexGPT или автоматизация сбора SEO-метрик, этот SDK станет вашим надежным помощником.
Top comments (0)