Yandex Search API на стероидах: обзор PHP-библиотеки yandex-search-php

Привет, dev.to! Сегодня мы погрузимся в мир программного доступа к поисковым технологиям Яндекса. Если вы когда-либо хотели интегрировать поиск Яндекса в свое PHP-приложение, создать кастомную поисковую выдачу, анализировать тренды с помощью Wordstat или даже использовать генеративные возможности YandexGPT, то эта статья для вас.

Речь пойдет о библиотеке yandex-search-php, которая представляет собой мощный и удобный SDK для работы с Yandex Search API. Мы разберем, почему стоит использовать именно эту библиотеку, как ее установить и какие возможности она открывает.

Зачем нужен SDK, если есть API?

Yandex Search API — это мощный инструмент, но работа с ним напрямую через HTTP-запросы может быть сопряжена с рядом рутинных задач:

1. Аутентификация: API требует использования IAM-токенов, которые нужно получать, используя OAuth-токен, и своевременно обновлять. Это лишний слой логики, который приходится реализовывать и поддерживать.


2. Обработка ответов: API возвращает данные в формате JSON. Для удобной и безопасной работы в коде эти данные нужно преобразовывать в объекты (DTO), что требует написания дополнительного кода.


3. Интеграция с фреймворками: При использовании фреймворков, таких как 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 все еще проще.

1. 
   

   Публикуем конфигурационный файл:
   
   

   
   

   php artisan vendor:publish --tag=yandex-search-config
   
   

   
   
   


2. 
   

   Добавляем учетные данные в .env:
   
   

   
   

   YANDEX_OAUTH_TOKEN=ваш_oauth_токен
   
   YANDEX_FOLDER_ID=ваш_folder_id
   
   

   
   
   


3. 
   

   Используем фасад или внедрение зависимостей:
   
   

   
   

   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 станет вашим надежным помощником.

Полезные ссылки

• Репозиторий yandex-search-php на GitHub
  


• Официальная документация Yandex Search API
  


• Документация по генеративным ответам