Les contrôleurs : Organiser la logique métier

Introduction aux contrôleurs : les chefs d'orchestre de votre application

Dans le modèle d'architecture logicielle MVC (Modèle-Vue-Contrôleur) sur lequel Laravel est basé, les contrôleurs jouent un rôle central. Ils agissent comme des intermédiaires entre les requêtes de l'utilisateur (généralement via les routes) et la logique métier de votre application (souvent incarnée par les modèles) ainsi que la présentation des données (gérée par les vues). Au lieu de définir toute la logique de gestion des requêtes directement dans vos fichiers de routes (via des closures), les contrôleurs vous permettent d'organiser ce code dans des classes dédiées.

L'utilisation des contrôleurs présente plusieurs avantages significatifs. Premièrement, elle améliore grandement l'organisation et la lisibilité de votre code, en particulier pour les applications de taille moyenne à grande. Le fichier routes/web.php reste concis, se concentrant sur la définition des URL et leur association à des méthodes de contrôleur. Deuxièmement, les contrôleurs favorisent la réutilisabilité du code ; une même méthode de contrôleur peut être appelée par différentes routes si nécessaire, ou contenir une logique partagée par plusieurs actions. Enfin, ils facilitent les tests unitaires et l'application des principes de conception logicielle comme le principe de responsabilité unique (SRP).

Ce chapitre vous guidera à travers la création et l'utilisation des contrôleurs dans Laravel. Vous apprendrez à générer des contrôleurs avec Artisan, à y définir des méthodes d'action pour répondre aux requêtes HTTP, et à retourner divers types de réponses, comme des vues Blade ou des données JSON.

Générer un contrôleur avec la commande Artisan `make:controller`

Laravel, via son puissant outil en ligne de commande Artisan, simplifie grandement la création de diverses classes, y compris les contrôleurs. Pour générer un nouveau contrôleur, vous utiliserez la commande make:controller.

La syntaxe de base est la suivante :

php artisan make:controller NomDuControleur

Par exemple, pour créer un contrôleur qui gérera les pages relatives aux articles de blog, vous pourriez exécuter :

php artisan make:controller ArticleController

Cette commande créera un nouveau fichier ArticleController.php dans le répertoire app/Http/Controllers. Par défaut, ce fichier contiendra une classe vide étendant le contrôleur de base de Laravel (App\Http\Controllers\Controller) :

Vous pouvez également générer des contrôleurs dans des sous-dossiers pour une meilleure organisation. Par exemple, pour un contrôleur d'administration des utilisateurs :

php artisan make:controller Admin/UserController

Cela créera le fichier UserController.php dans app/Http/Controllers/Admin et ajustera l'espace de noms (namespace) en conséquence (App\Http\Controllers\Admin).

Laravel offre des options pour générer des contrôleurs avec des méthodes prédéfinies, particulièrement utiles pour les opérations CRUD (Create, Read, Update, Delete). Un contrôleur de ressources peut être généré avec l'option --resource ou -r :

php artisan make:controller PhotoController --resource

Cela créera un PhotoController avec des méthodes "stub" pour les actions typiques d'une ressource : index, create, store, show, edit, update, et destroy. Si vous construisez une API, vous pouvez utiliser l'option --api pour générer un contrôleur de ressources API, qui omettra les méthodes create et edit (généralement utilisées pour afficher des formulaires HTML) :

php artisan make:controller Api/ProductController --api

Il existe aussi des contrôleurs "invokables" (--invokable ou -i) qui sont conçus pour effectuer une seule action. Ils contiennent une unique méthode __invoke.

Créer des méthodes d'action dans les contrôleurs

Une fois votre contrôleur généré, vous pouvez y ajouter des méthodes publiques. Chaque méthode publique dans un contrôleur peut potentiellement servir de "méthode d'action", c'est-à-dire une fonction qui sera exécutée lorsqu'une route pointe vers elle.

Prenons notre ArticleController. Nous pourrions y ajouter une méthode pour afficher la liste de tous les articles et une autre pour afficher un article spécifique :

 $articles]);
    }

    /**
     * Affiche un article spécifique.
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     */
    public function show($id)
    {
        $article = Article::findOrFail($id); // Récupère l'article ou échoue avec une erreur 404
        return view('articles.show', ['article' => $article]);
    }
}

Dans cet exemple, la méthode index récupère tous les articles (en supposant l'existence d'un modèle Article) et les passe à une vue nommée articles.index. La méthode show attend un paramètre $id (qui sera fourni par la route), récupère l'article correspondant, et le passe à une vue articles.show.

Pour lier ces méthodes à des routes, vous mettriez à jour votre fichier routes/web.php (ou routes/api.php) comme suit :

use App\Http\Controllers\ArticleController;

Route::get('/articles', [ArticleController::class, 'index'])->name('articles.index');
Route::get('/articles/{id}', [ArticleController::class, 'show'])->name('articles.show');

La syntaxe [Controleur::class, 'methode'] est la manière standard de référencer une méthode de contrôleur depuis Laravel 8. Elle est plus robuste aux refactorisations que l'ancienne syntaxe basée sur des chaînes de caractères.

Vos méthodes d'action peuvent utiliser l'injection de dépendances de Laravel pour recevoir automatiquement des instances d'objets dont elles ont besoin, comme l'instance de la requête HTTP actuelle (Illuminate\Http\Request) ou des paramètres de route. Si votre route est /articles/{article} et que vous typez l'argument $article avec votre modèle Eloquent Article (par exemple, public function show(Article $article)), Laravel tentera automatiquement de trouver une instance du modèle Article correspondant à l'ID passé dans l'URL. C'est ce qu'on appelle le "Route Model Binding", une fonctionnalité très pratique.

Retourner des réponses depuis un contrôleur

Chaque méthode d'action dans un contrôleur doit retourner une réponse HTTP. Laravel est flexible quant au type de réponse que vous pouvez retourner. Les types de réponses les plus courants sont :

• Des vues Blade : Pour les applications web traditionnelles, vous retournerez souvent une vue en utilisant la fonction helper view().
• Des données JSON : Pour les API ou les requêtes AJAX, vous retournerez généralement un tableau ou un objet qui sera automatiquement converti en JSON.
• Des redirections : Après une action comme la soumission d'un formulaire, vous redirigerez souvent l'utilisateur vers une autre page.
• Des réponses HTTP simples : Pour des cas spécifiques, vous pouvez retourner des chaînes, des codes de statut HTTP spécifiques, ou des réponses personnalisées.

Exemple de retour d'une vue (déjà vu) :

public function index()
{
    $donnees = ['cle' => 'valeur'];
    return view('ma_vue', $donnees);
}

Exemple de retour de JSON :

use App\Models\User;

public function utilisateursApi()
{
    $utilisateurs = User::all();
    return response()->json($utilisateurs);
    // Ou plus simplement, si $utilisateurs est une Collection Eloquent ou un tableau :
    // return $utilisateurs;
    // Laravel le convertira automatiquement en JSON.
}

Vous pouvez également spécifier un code de statut HTTP avec la réponse JSON : return response()->json(['error' => 'Non autorisé'], 401);

Exemple de redirection :

public function store(Request $request)
{
    // Logique pour sauvegarder des données...
    // ...

    // Rediriger vers une route nommée
    return redirect()->route('articles.index')->with('message', 'Article créé avec succès !');

    // Rediriger vers une URL spécifique
    // return redirect('/accueil');

    // Rediriger vers l'action d'un autre contrôleur
    // return redirect()->action([AutreController::class, 'autreMethode']);

    // Rediriger vers la page précédente
    // return back()->withInput();
}

La méthode with() permet de "flasher" des données dans la session, qui seront disponibles uniquement pour la prochaine requête (typiquement pour afficher des messages de succès ou d'erreur après une redirection).

En résumé, les contrôleurs sont des éléments essentiels pour structurer vos applications Laravel. Ils séparent les préoccupations, rendent votre code plus propre, plus maintenable et plus facile à tester, tout en offrant une grande flexibilité dans la gestion des requêtes et la génération des réponses.