README

Полнофункциональный PHP 8.3 клиент для работы с неофициальным API KinoPoisk.dev. Библиотека предоставляет удобный объектно-ориентированный интерфейс для доступа ко всем возможностям API с полной поддержкой типов, кэширования и детальной документацией на русском языке.

🎯 Возможности

✅ Полное покрытие API v1.4 - поддержка всех доступных эндпоинтов
✅ PHP 8.3+ - использование современных возможностей языка
✅ Типизация - полная поддержка типов для IDE и статического анализа
✅ Кэширование - встроенная поддержка кэширования запросов
✅ Удобные фильтры - мощная система фильтрации с fluent interface
✅ Документация на русском - подробная документация и примеры
✅ Обработка ошибок - продуманная система исключений
✅ PSR-совместимость - следование стандартам PHP

📦 Установка

Через Composer

composer require devcraftclub/kinopoisk-dev-php

Требования

PHP >= 8.3
Guzzle HTTP >= 7.0
Токен API от kinopoisk.dev

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

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

Для работы с API необходимо получить токен через Telegram бота:

Напишите боту @kinopoiskdev_bot в Telegram
Следуйте инструкциям бота для получения токена

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

<?php

require_once 'vendor/autoload.php';

use KinopoiskDev\Http\MovieRequests;
use KinopoiskDev\Filter\MovieSearchFilter;
use KinopoiskDev\Exceptions\KinopoiskDevException;

// Инициализация клиента
$apiToken = 'ваш_токен_здесь';
$movieClient = new MovieRequests($apiToken);

try {
    // Получение фильма по ID
    $movie = $movieClient->getMovieById(666);
    echo "Фильм: {$movie->name} ({$movie->year})\n";
    echo "Рейтинг КП: {$movie->rating->kp}\n";

    // Поиск фильмов с фильтрами
    $filter = new MovieSearchFilter();
    $filter->withRatingBetween(8.0, 10.0)
           ->withYearBetween(2020, 2024)
           ->withIncludedGenres(['драма', 'триллер'])
           ->onlyMovies();

    $results = $movieClient->searchMovies($filter, 1, 10);
    echo "Найдено: {$results->total} фильмов\n";

} catch (KinopoiskDevException $e) {
    echo "Ошибка API: " . $e->getMessage() . "\n";
}

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

Автоматическая генерация документации

Проект включает в себя автоматический генератор документации, который создает полную документацию на основе PHPDoc комментариев.

Генерация документации

# Способ 1: Прямой вызов
php bin/generate_docs.php

# Способ 2: Через composer
composer docs

Документация будет создана в папке docs/ и включает:

Классы - полная документация всех классов с методами и свойствами
Интерфейсы - документация интерфейсов и их методов
Enum'ы - документация enum'ов со всеми cases и их значениями
Trait'ы - документация trait'ов и их методов
PHPDoc теги - поддержка всех стандартных PHPDoc тегов:
- @param, @return, @throws
- @example, @see, @since
- {@inheritDoc} - наследование документации из родительских классов/интерфейсов
- Сложные типы: array<string, mixed>, int|null, etc.

Структура документации

docs/
├── README.md                    # Главная страница с навигацией
├── Kinopoisk.md                # Основной класс Kinopoisk
├── Models/                     # Модели данных
│   ├── Movie.md
│   ├── Person.md
│   └── ...
├── Http/                       # HTTP клиенты
│   ├── MovieRequests.md
│   ├── PersonRequests.md
│   └── ...
├── Enums/                      # Enum'ы
│   ├── MovieType.md
│   ├── PersonProfession.md
│   └── ...
├── Contracts/                  # Интерфейсы
│   ├── CacheInterface.md
│   └── LoggerInterface.md
└── Utils/                      # Утилиты и trait'ы
    ├── FilterTrait.md
    ├── SortManager.md
    └── ...

Особенности генератора

Автоматическое наследование - {@inheritDoc} наследует документацию из родительских классов/интерфейсов
Поддержка всех типов PHP - классы, интерфейсы, enum'ы, trait'ы
Сложные типы - правильное отображение array<string, mixed>, union типов
Многострочные описания - сохранение форматирования в PHPDoc
Примеры кода - поддержка @example тегов с подсветкой синтаксиса

🤝 Вклад в проект

Мы приветствуем ваш вклад в развитие проекта! Пожалуйста:

Форкните репозиторий
Создайте ветку для новой функции (git checkout -b feature/amazing-feature)
Зафиксируйте изменения (git commit -m 'Add amazing feature')
Отправьте в ветку (git push origin feature/amazing-feature)
Откройте Pull Request

Требования к коду

Следуйте PSR-12 стандарту
Добавляйте PHPDoc комментарии на русском языке
Покрывайте код тестами
Обновляйте документацию

🔄 Автоматические обновления

Проект использует Dependabot для автоматического обновления зависимостей:

Composer зависимости - обновляются еженедельно по понедельникам
GitHub Actions - обновляются еженедельно по понедельникам
Автоматическое слияние - patch и minor обновления сливаются автоматически
Major обновления - требуют ручного ревью для критических зависимостей

Dependabot создает Pull Request'ы с обновлениями зависимостей, которые:

Автоматически проходят тесты
Генерируют обновленную документацию
Помечаются соответствующими лейблами
Назначаются на команду разработки для ревью

📄 Лицензия

Этот проект лицензирован под лицензией MIT - см. файл LICENSE для деталей.

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

📞 Поддержка

Если у вас есть вопросы или проблемы:

Проверьте существующие issues
Создайте новый issue с детальным описанием
Напишите в Telegram чат

devcraftclub / kinopoisk-dev-php

Maintainers

Details