Capítulo 2.4: Controlador API PlanetController

Tempo de estudo: 1 hora

---

1. Controlador: Centro de Controle de Objetos Espaciais

Na arquitetura MVC, o controlador é o intermediário entre os modelos e as requisições:

• 📡 Aceita requisições HTTP (GET, POST, PUT, DELETE)
• 🔍 Extrai dados do banco através dos modelos
• 📦 Formata respostas JSON para a API

💡 Analogia Espacial: PlanetController = Centro de Controle da Missão:

• Recebe requisições da Terra (GET /planets)
• Dá comandos às "sondas" (modelos)
• Retorna telemetria em formato JSON

---

2. Criação de um Controlador de Recurso

Um controlador de recurso inclui automaticamente métodos para operações CRUD.

Passo 1: Geração do Controlador

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

O que será criado em app/Http/Controllers/PlanetController.php:

<?php

namespace App\Http\Controllers;

use App\Models\Planet;
use Illuminate\Http\Request;
use Illuminate\Validation\Rule; // Não se esqueça de adicionar esta importação

class PlanetController extends Controller
{
    // Mostrar lista de planetas
    public function index(Request $request) {}

    // Criar um novo planeta
    public function store(Request $request) {}

    // Mostrar um planeta específico
    public function show(Planet $planet) {}

    // Atualizar um planeta
    public function update(Request $request, Planet $planet) {}

    // Excluir um planeta
    public function destroy(Planet $planet) {}
}

---

3. Implementação dos Métodos da API

A. index() - Obtenção da lista de planetas

<?php
public function index(Request $request)
{
    // Obtém os planetas com paginação, 15 por página
    $planets = Planet::paginate($request->get('per_page', 15));
    return response()->json($planets); // Automaticamente 200 OK
}

B. store() - Criação de um novo planeta

<?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() - Visualização de um planeta

<?php
public function show(Planet $planet)
{
    return response()->json($planet); // Automaticamente 200 OK
}

D. update() - Atualização de um planeta

<?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' - validar, apenas se o campo for fornecido
        '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() - Exclusão de um planeta

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

---

4. Vinculação de Modelo (Route Model Binding)

O Laravel automaticamente injeta o objeto do planeta pelo ID:

// Na rota: GET /planets/{planet}
// No método: show(Planet $planet)

• Se o planeta não for encontrado → automaticamente 404
• Não há necessidade de requisições manuais findOrFail()

---

5. Formatação de Respostas

Exemplo de resposta aprimorada para index():

<?php
public function index()
{
    return response()->json([
        'success' => true,
        'data' => Planet::all(),
        'message' => 'Planetas obtidos com sucesso'
    ]);
}

Resposta em caso de erro 404 (automaticamente):

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

---

Questionário para fixação

1. Flag para criar um controlador API:

a) --api b) --resource c) --model

2. Qual status retornar em caso de criação bem-sucedida?

a) 200 OK b) 201 Created c) 204 No Content

3. O Route Model Binding permite:

a) Obter automaticamente o objeto por ID b) Gerar formulários HTML c) Armazenar em cache as requisições

4. Ao excluir um planeta, retornamos:

a) JSON com os dados do planeta b) null com código 204 c) Uma string vazia

5. $request->validate() é usado para:

a) Validação de dados de entrada b) Criptografia de requisições c) Armazenamento em cache de respostas

Verificar

---

🚀 Resumo do capítulo:

Você criou um "painel de controle" para o sistema planetário! Agora seu controlador consegue:

• 🌌 Mostrar a lista de planetas (index)
• 🪐 Criar novos mundos (store)
• 🔭 Detalhar os dados de um planeta (show)
• 🛠️ Atualizar informações (update)
• 💥 Destruir planetas (destroy)

Resta definir as rotas! No próximo capítulo, conectaremos o controlador às rotas da API.

📌 Verificação:

Certifique-se de que app/Http/Controllers contém PlanetController.php com 5 métodos.

⚠️ Se houver erros:

• Verifique o nome do modelo: use App\Models\Planet;
• Verifique as importações
• Para PostgreSQL: certifique-se de que Planet::all() retorna dados
• Em caso de problemas com o Tinker: execute composer dump-autoload