ВДНХ Афиша API (Тестовое задание)

Бэкенд-приложение для фильтрации и вывода афиши событий Выставки (ВДНХ) на основе предоставленного технического задания.

🛠 Стек технологий

PHP: 8.2 / 8.3
Framework: Laravel 12.x
Database: MySQL / PostgreSQL
API Specification: Postman (коллекция в корне проекта)

📋 Постановка задачи

Разработать JSON API для Афиши событий (https://vdnh.ru/) со следующими требованиями:

Метод API для фильтрации событий по нескольким категориям и промежутку дат.
Реализация пагинации для списка событий.
Наличие сидеров (Database Seeding) для наполнения тестовыми данными.
Публикация на GitHub + предоставление коллекции для Postman.

🚀 Развертывание проекта

Выполните последовательно следующие команды в терминале:

Клонирование репозитория и установка зависимостей:
```
composer install
```
Настройка окружения:
```
cp .env.example .env
php artisan key:generate
```
Отредактируйте файл .env, указав ваши доступы к базе данных (DB_DATABASE, DB_USERNAME, DB_PASSWORD).
Миграции и наполнение базы (Сидинг):
```
php artisan migrate:fresh --seed
```
💡 Что произойдет: Команда полностью пересоздаст структуру БД и запустит сидеры, которые сгенерируют 11 реальных категорий и 40 тестовых событий со случайными датами для удобной проверки фильтрации.
Пользователи:
- В базе уже есть сгенерирован "test@example.com" с паролем "password".
- Чтобы использовать другие методы, находящиеся под защитой Sanctum, необходимо вызвать метод /api/login) и получить токен, который сохранится в переменную token в POSTMAN.
- Для генерации нового пользователя или изменения его пароля/токена можно воспользоваться консольными командами, описанными ниже.

💻 Консольные команды (CLI)

Для удобства управления пользователями и токенами добавлены кастомные Artisan-команды:

Создание пользователя и генерация API-токена:
```
php artisan user:create-api-user "Ivan Ivanov" ivan@example.com "secret123"
```
Команда регистрирует нового пользователя в базе данных и сразу генерирует для него первый Sanctum-токен.
Сброс пароля и выдача нового токена:
```
php artisan user:reset-password ivan@example.com "new_secret123"
```
Команда находит пользователя по email, обновляет его пароль и выводит в консоль новый рабочий Sanctum-токен.

📡 Документация API (Эндпоинты)

Для всех запросов обязательно передавайте заголовки:

Accept: application/json
Content-Type: application/json

1. Авторизация (Получение токена)

URL: /api/login
Метод: POST

Тело запроса (JSON):

{
    "email": "user@example.com",
    "password": "your_password"
}

2. Выход из системы (Logout)

URL: /api/logout
Метод: POST
Описание: Деактивирует и удаляет текущий API-токен Sanctum, с которым был выполнен запрос. Заговоловок Authorization c токеном обязателен.

В ответе возвращаются данные пользователя и его access_token для авторизации в защищенных эндпоинтах.

3. Получение данных пользователя

URL: /api/user
Метод: POST
Описание:: описание пользователя, заговоловок Authorization c токеном обязателен.

4. Получение списка событий с фильтрацией и пагинацией

URL: /api/gigs
Метод: GET
Описание: для метода необходим заголовок Authorization: Bearer {{token}}, который можно получить методом /login.

Параметры запроса (Query Parameters):

Параметр	Тип	Обязательный	Описание	Пример / Значение
`categories`	`array`	Нет	Массив ID или слагов категорий	`categories[]=1&categories[]=2`
`date_from`	`string`	Нет	Начало диапазона дат (`YYYY-MM-DD`)	`2026-05-01`
`date_to`	`string`	Нет	Конец диапазона дат (`YYYY-MM-DD`)	`2026-05-31`
`page`	`integer`	Нет	Номер страницы пагинации	`2`
`per_page`	`integer`	Нет	Количество элементов на страницу	`15` (По умолчанию: `10`)

Пример запроса:

GET /api/gigs?categories[]=1&categories[]=4&date_from=2026-02-01&date_to=2026-05-31

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

В корне репозитория находится файл коллекции для быстрого тестирования всех эндпоинтов: gigs_api_collection.json.

6.5 KiB Raw Blame History Unescape Escape