nulldec0de/yandex-search-api-php-client

PHP клиент для работы с Yandex Search API

dev-main 2025-10-30 12:28 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• psr/log: ^1.0|^2.0|^3.0

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• nulldec0de

• api
• search
• yandex
• search-api
• yandex-cloud
• yandex-search

README

PHP клиент для работы с Yandex Search API. Позволяет выполнять поисковые запросы через Yandex Cloud Search API и получать результаты поиска. Может использоваться для поиска позиций вашего сайта.

Возможности

• Автоматическое управление IAM токенами (обновление при истечении)
• Поддержка различных типов поиска (русский, турецкий, международный)
• Поддержка множества регионов России и других стран
• Асинхронные запросы с проверкой статуса операции
• Извлечение ссылок из XML результатов
• Интеграция с PSR-3 логгерами
• Полная поддержка типов (PHP 8.1+)

Требования

• PHP 8.1 или выше
• Composer
• OAuth токен от Yandex
• Folder ID в Yandex Cloud

Установка

Через Composer

composer require nulldec0de/yandex-search-api-php-client

Ручная установка

1. Клонируйте репозиторий:

git clone https://github.com/NullDec0de/YandexSearchAPI-php.git

1. Установите зависимости:

composer install

Быстрый старт

Базовое использование

<?php

require_once 'vendor/autoload.php';

use YandexSearchAPI\YandexSearchAPIClient;
use YandexSearchAPI\SearchType;
use YandexSearchAPI\Region;

// Инициализация клиента
$client = new YandexSearchAPIClient(
    folderId: 'your-folder-id',
    oauthToken: 'your-oauth-token'
);

// Простой поиск с ожиданием результатов
try {
    $links = $client->getLinks(
        queryText: 'PHP programming',
        searchType: SearchType::RUSSIAN,
        region: Region::MOSCOW_AND_MOSCOW_REGION,
        nLinks: 10
    );
    
    foreach ($links as $link) {
        echo $link . "\n";
    }
} catch (\YandexSearchAPI\YandexSearchAPIError $e) {
    echo "Ошибка: " . $e->getMessage() . "\n";
}

Расширенное использование

<?php

use YandexSearchAPI\YandexSearchAPIClient;
use YandexSearchAPI\SearchType;
use YandexSearchAPI\Region;
use Psr\Log\LoggerInterface;

// С кастомным логгером
$logger = new MyCustomLogger();
$client = new YandexSearchAPIClient(
    folderId: 'your-folder-id',
    oauthToken: 'your-oauth-token',
    logger: $logger
);

// Асинхронный поиск
$operationId = $client->search(
    queryText: 'Yandex Cloud',
    searchType: SearchType::RUSSIAN,
    region: Region::RUSSIA,
    page: 0,
    nLinks: 20
);

// Проверка статуса и получение результатов
sleep(2);
$xmlResults = $client->getSearchResults($operationId);

// Извлечение ссылок из XML
$links = YandexSearchAPIClient::extractYandexSearchLinks($xmlResults);

Поиск с ожиданием результатов

<?php

$client = new YandexSearchAPIClient(
    folderId: 'your-folder-id',
    oauthToken: 'your-oauth-token'
);

// Автоматическое ожидание результатов с таймаутом
try {
    $xmlResults = $client->searchAndWait(
        queryText: 'Python tutorials',
        searchType: SearchType::INTERNATIONAL,
        region: Region::RUSSIA,
        maxWait: 300,  // максимум 5 минут ожидания
        interval: 1,   // проверка каждую секунду
        nLinks: 15
    );
    
    $links = YandexSearchAPIClient::extractYandexSearchLinks($xmlResults);
} catch (\YandexSearchAPI\YandexSearchTimeoutError $e) {
    echo "Таймаут: " . $e->getMessage() . "\n";
}

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

YandexSearchAPIClient

Конструктор

public function __construct(
    string $folderId,
    string $oauthToken,
    ?LoggerInterface $logger = null,
    ?Client $httpClient = null
)

Параметры:

• $folderId - ID папки в Yandex Cloud (обязательный)
• $oauthToken - OAuth токен от Yandex (обязательный)
• $logger - Экземпляр PSR-3 логгера (опционально)
• $httpClient - Кастомный Guzzle HTTP клиент (опционально)

Методы

search()

Выполняет поисковый запрос и возвращает ID операции.

public function search(
    string $queryText,
    SearchType $searchType = SearchType::RUSSIAN,
    Region $region = Region::RUSSIA,
    int $page = 0,
    int $nLinks = 10,
    float $responseTimeout = 5.0
): string

Параметры:

• $queryText - Текст поискового запроса
• $searchType - Тип поиска (по умолчанию SearchType::RUSSIAN)
• $region - Регион поиска (по умолчанию Region::RUSSIA)
• $page - Номер страницы результатов (по умолчанию 0)
• $nLinks - Количество ссылок на странице (по умолчанию 10)
• $responseTimeout - Таймаут ответа в секундах (по умолчанию 5.0)

Возвращает: ID операции (string)

Исключения: YandexSearchAPIError

getSearchResults()

Получает результаты поиска по ID операции.

public function getSearchResults(string $operationId): string

Параметры:

• $operationId - ID операции, полученный из метода search()

Возвращает: XML контент с результатами поиска (string)

Исключения: YandexSearchAPIError

searchAndWait()

Выполняет поиск и ожидает завершения операции с автоматической проверкой статуса.

public function searchAndWait(
    string $queryText,
    SearchType $searchType = SearchType::RUSSIAN,
    Region $region = Region::RUSSIA,
    int $maxWait = 300,
    int $interval = 1,
    int $nLinks = 10
): string

Параметры:

• $queryText - Текст поискового запроса
• $searchType - Тип поиска
• $region - Регион поиска
• $maxWait - Максимальное время ожидания в секундах (по умолчанию 300)
• $interval - Интервал проверки статуса в секундах (по умолчанию 1)
• $nLinks - Количество ссылок на странице

Возвращает: XML контент с результатами поиска (string)

Исключения: YandexSearchTimeoutError, YandexSearchAPIError

getLinks()

Удобный метод для получения только ссылок из результатов поиска.

public function getLinks(
    string $queryText,
    SearchType $searchType = SearchType::RUSSIAN,
    Region $region = Region::RUSSIA,
    int $nLinks = 10,
    int $maxWait = 300,
    int $interval = 1
): array

Возвращает: Массив URL-адресов (string[])

Исключения: YandexSearchTimeoutError, YandexSearchAPIError

extractYandexSearchLinks()

Статический метод для извлечения ссылок из XML контента.

public static function extractYandexSearchLinks(string $xmlContent): array

Параметры:

• $xmlContent - XML контент с результатами поиска

Возвращает: Массив URL-адресов (string[])

Enums

SearchType

Типы поиска:

• SearchType::RUSSIAN - Поиск по русскоязычному интернету
• SearchType::TURKISH - Поиск по турецкому интернету
• SearchType::INTERNATIONAL - Международный поиск

Region

Поддерживаемые регионы включают:

• Region::RUSSIA - Вся Россия
• Region::MOSCOW_AND_MOSCOW_REGION - Москва и Московская область
• Region::SAINT_PETERSBURG - Санкт-Петербург
• Region::EKATERINBURG - Екатеринбург
• Region::NOVOSIBIRSK - Новосибирск
• И многие другие регионы России и стран СНГ

Полный список регионов доступен в файле Enums.php.

ResponseFormat

Форматы ответа:

• ResponseFormat::XML - XML формат
• ResponseFormat::HTML - HTML формат

Исключения

• YandexSearchAPIError - Базовое исключение для всех ошибок API
• YandexSearchTimeoutError - Исключение при таймауте ожидания результатов
• YandexAuthError - Исключение при ошибках аутентификации

Получение OAuth токена

1. Перейдите на Yandex OAuth
2. Создайте новое приложение
3. Получите OAuth токен

Получение Folder ID

1. Войдите в Yandex Cloud Console
2. Выберите или создайте облако
3. Создайте каталог (folder)
4. Скопируйте Folder ID из адресной строки или настроек каталога

Примеры использования

Поиск по разным регионам

use YandexSearchAPI\Region;

$regions = [
    Region::MOSCOW_AND_MOSCOW_REGION,
    Region::SAINT_PETERSBURG,
    Region::EKATERINBURG
];

foreach ($regions as $region) {
    $links = $client->getLinks(
        queryText: 'рестораны',
        region: $region,
        nLinks: 5
    );
    
    echo "Регион: {$region->value}\n";
    foreach ($links as $link) {
        echo "  - $link\n";
    }
}

Работа с пагинацией

for ($page = 0; $page < 3; $page++) {
    $operationId = $client->search(
        queryText: 'PHP разработка',
        page: $page,
        nLinks: 10
    );
    
    sleep(2);
    $results = $client->getSearchResults($operationId);
    $links = YandexSearchAPIClient::extractYandexSearchLinks($results);
    
    echo "Страница " . ($page + 1) . ":\n";
    foreach ($links as $link) {
        echo "  - $link\n";
    }
}

Обработка ошибок

try {
    $links = $client->getLinks('test query');
} catch (\YandexSearchAPI\YandexAuthError $e) {
    echo "Ошибка аутентификации: " . $e->getMessage() . "\n";
} catch (\YandexSearchAPI\YandexSearchTimeoutError $e) {
    echo "Таймаут: " . $e->getMessage() . "\n";
} catch (\YandexSearchAPI\YandexSearchAPIError $e) {
    echo "Ошибка API: " . $e->getMessage() . "\n";
} catch (\Exception $e) {
    echo "Неожиданная ошибка: " . $e->getMessage() . "\n";
}

Логирование

Клиент поддерживает PSR-3 логгеры:

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('yandex_search');
$logger->pushHandler(new StreamHandler('php://stdout', Logger::DEBUG));

$client = new YandexSearchAPIClient(
    folderId: 'your-folder-id',
    oauthToken: 'your-oauth-token',
    logger: $logger
);

Требования к системе

• PHP 8.1+
• Расширение ext-json
• Расширение ext-xml
• Расширение ext-curl (для Guzzle)

Тестирование

composer test

Поддержка

Если у вас возникли вопросы или проблемы:

1. Проверьте документацию Yandex Search API
2. Создайте Issue на GitHub
3. Убедитесь, что ваши OAuth токен и Folder ID корректны