Skip to content

Глава 2.4: API контроллер PlanetController

Время изучения: 1 час


1. Контроллер: Центр управления космическими объектами

В MVC-архитектуре контроллер - это посредник между моделями и запросами:

  • 📡 Принимает HTTP-запросы (GET, POST, PUT, DELETE)
  • 🔍 Извлекает данные из базы через модели
  • 📦 Формирует JSON-ответы для API

💡 Космическая аналогия: PlanetController = ЦУП миссии:

  • Получает запросы с Земли (GET /planets)
  • Отдает команды "зондам" (моделям)
  • Возвращает телеметрию в JSON-формате

2. Создание ресурсного контроллера

Ресурсный контроллер автоматически включает методы для CRUD-операций.

Шаг 1: Генерация контроллера

php artisan make:controller PlanetController --api --model=Planet

Что создастся в app/Http/Controllers/PlanetController.php:

<?php

namespace App\Http\Controllers;

use App\Models\Planet;
use Illuminate\Http\Request;
use Illuminate\Validation\Rule; // Не забудь добавить этот импорт

class PlanetController extends Controller
{
    // Показать список планет
    public function index(Request $request) {}

    // Создать новую планету
    public function store(Request $request) {}

    // Показать конкретную планету
    public function show(Planet $planet) {}

    // Обновить планету
    public function update(Request $request, Planet $planet) {}

    // Удалить планету
    public function destroy(Planet $planet) {}
}


3. Реализация методов API

A. index() - Получение списка планет

<?php
public function index(Request $request)
{
    // Получаем планеты с пагинацией, по 15 на страницу
    $planets = Planet::paginate($request->get('per_page', 15));
    return response()->json($planets); // Автоматически 200 OK
}

B. store() - Создание новой планеты

<?php
public function store(Request $request)
{
    $data = $request->validate([
        'name' => 'required|string|max:255|unique:planets',
        'description' => 'required|string',
        'size_km' => 'required|integer|min:100',
        'solar_system' => 'required|string|max:100',
        'image_url' => 'nullable|url',
        'is_habitable' => 'boolean'
    ]);

    $planet = Planet::create($data);
    return response()->json($planet, 201); // 201 Created
}

C. show() - Просмотр одной планеты

<?php
public function show(Planet $planet)
{
    return response()->json($planet); // Автоматический 200 OK
}

D. update() - Обновление планеты

<?php
public function update(Request $request, Planet $planet)
{
    $data = $request->validate([
        'name' => [
            'string',
            'max:255',
            Rule::unique('planets')->ignore($planet->id),
        ],
        'description' => 'sometimes|string', // 'sometimes' - валидировать, только если поле пришло
        'size_km' => 'sometimes|integer|min:100',
        'solar_system' => 'sometimes|string|max:100',
        'image_url' => 'sometimes|nullable|url',
        'is_habitable' => 'sometimes|boolean'
    ]);

    $planet->update($data);
    return response()->json($planet); // 200 OK
}

E. destroy() - Удаление планеты

<?php
public function destroy(Planet $planet)
{
    $planet->delete();
    return response()->json(null, 204); // 204 No Content
}


4. Привязка модели (Route Model Binding)

Laravel автоматически подставляет объект планеты по ID:

// В роуте: GET /planets/{planet}
// В методе: show(Planet $planet)

  • Если планета не найдена → автоматически 404
  • Нет нужды в ручных запросах findOrFail()

5. Форматирование ответов

Пример улучшенного ответа для index():

<?php
public function index()
{
    return response()->json([
        'success' => true,
        'data' => Planet::all(),
        'message' => 'Планеты успешно получены'
    ]);
}

Ответ при ошибке 404 (автоматически):

{
    "message": "No query results for model [App\\Models\\Planet] 123",
    "exception": "Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException"
}


Квиз для закрепления

1. Флаг для создания API-контроллера:

2. Какой статус возвращать при успешном создании?

3. Route Model Binding позволяет:

4. При удалении планеты возвращаем:

5. $request->validate() используется для:


🚀 Итог главы:

Вы создали "пульт управления" планетарной системой! Теперь ваш контроллер умеет:

  • 🌌 Показывать список планет (index)
  • 🪐 Создавать новые миры (store)
  • 🔭 Детализировать данные планеты (show)
  • 🛠️ Обновлять сведения (update)
  • 💥 Уничтожать планеты (destroy)

Осталось проложить маршруты! В следующей главе мы подключим контроллер к API-роутам.

📌 Проверка:

Убедитесь, что в app/Http/Controllers есть PlanetController.php с 5 методами.

⚠️ Если ошибки:

  • Проверьте название модели: use App\Models\Planet;
  • Проверьте импорты
  • Для PostgreSQL: убедитесь что Planet::all() возвращает данные
  • При проблемах с Tinker: выполните composer dump-autoload