Chapitre 2.4 : Contrôleur API PlanetController

Temps d'étude : 1 heure

---

1. Contrôleur : Centre de contrôle des objets spatiaux

Dans l'architecture MVC, le contrôleur est un intermédiaire entre les modèles et les requêtes :

• 📡 Reçoit les requêtes HTTP (GET, POST, PUT, DELETE)
• 🔍 Extrait les données de la base via les modèles
• 📦 Forme les réponses JSON pour l'API

💡 Analogie spatiale : PlanetController = Centre de Contrôle des Missions :

• Reçoit les requêtes de la Terre (GET /planets)
• Donne des commandes aux "sondes" (modèles)
• Retourne la télémétrie au format JSON

---

2. Création d'un contrôleur de ressources

Un contrôleur de ressources inclut automatiquement des méthodes pour les opérations CRUD.

Étape 1 : Génération du contrôleur

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

Ce qui sera créé dans app/Http/Controllers/PlanetController.php :

<?php

namespace App\Http\Controllers;

use App\Models\Planet;
use Illuminate\Http\Request;
use Illuminate\Validation\Rule; // N'oubliez pas d'ajouter cette importation

class PlanetController extends Controller
{
    // Afficher la liste des planètes
    public function index(Request $request) {}

    // Créer une nouvelle planète
    public function store(Request $request) {}

    // Afficher une planète spécifique
    public function show(Planet $planet) {}

    // Mettre à jour une planète
    public function update(Request $request, Planet $planet) {}

    // Supprimer une planète
    public function destroy(Planet $planet) {}
}

---

3. Implémentation des méthodes d'API

A. index() - Récupération de la liste des planètes

<?php
public function index(Request $request)
{
    // Récupérons les planètes avec pagination, 15 par page
    $planets = Planet::paginate($request->get('per_page', 15));
    return response()->json($planets); // Automatiquement 200 OK
}

B. store() - Création d'une nouvelle planète

<?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() - Affichage d'une seule planète

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

D. update() - Mise à jour d'une planète

<?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' - valider uniquement si le champ est présent
        '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() - Suppression d'une planète

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

---

4. Liaison de modèle de route (Route Model Binding)

Laravel substitue automatiquement l'objet planète par ID :

// Dans la route : GET /planets/{planet}
// Dans la méthode : show(Planet $planet)

• Si la planète n'est pas trouvée → automatiquement 404
• Pas besoin de requêtes manuelles findOrFail()

---

5. Formatage des réponses

Exemple de réponse améliorée pour index() :

<?php
public function index()
{
    return response()->json([
        'success' => true,
        'data' => Planet::all(),
        'message' => 'Planètes récupérées avec succès'
    ]);
}

Réponse en cas d'erreur 404 (automatique) :

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

---

Quiz pour la consolidation

1. Le drapeau pour créer un contrôleur API :

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

2. Quel statut renvoyer en cas de création réussie ?

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

3. Le Route Model Binding permet de :

a) Obtenir automatiquement un objet par ID b) Générer des formulaires HTML c) Mettre en cache les requêtes

4. Lors de la suppression d'une planète, nous renvoyons :

a) JSON avec les données de la planète b) null avec le code 204 c) Une chaîne vide

5. `$request->validate()` est utilisé pour :

a) La validation des données d'entrée b) Le chiffrement des requêtes c) La mise en cache des réponses

Vérifier

---

🚀 Résumé du chapitre :

Vous avez créé le "tableau de bord" du système planétaire ! Votre contrôleur est maintenant capable de :

• 🌌 Afficher la liste des planètes (index)
• 🪐 Créer de nouveaux mondes (store)
• 🔭 Détailler les données d'une planète (show)
• 🛠️ Mettre à jour les informations (update)
• 💥 Détruire des planètes (destroy)

Il ne reste plus qu'à définir les routes ! Dans le chapitre suivant, nous connecterons le contrôleur aux routes d'API.

📌 Vérification :

Assurez-vous que PlanetController.php se trouve dans app/Http/Controllers avec 5 méthodes.

⚠️ En cas d'erreurs :

• Vérifiez le nom du modèle : use App\Models\Planet;
• Vérifiez les importations
• Pour PostgreSQL : assurez-vous que Planet::all() renvoie des données
• En cas de problèmes avec Tinker : exécutez composer dump-autoload