> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Contrôleurs

> Comment créer des contrôleurs Laravel et les intégrer au routage.

## Qu'est-ce qu'un contrôleur

Au lieu de définir toute la logique de traitement des requêtes dans des closures dans les fichiers de routes, vous pouvez organiser ce comportement dans des classes « contrôleurs ».
Un contrôleur regroupe la logique de traitement des requêtes liées dans une seule classe.

Par exemple, la classe `UserController` peut gérer toutes les requêtes concernant les utilisateurs (affichage, création, mise à jour, suppression, etc.).
Par défaut, les contrôleurs sont stockés dans le répertoire `app/Http/Controllers`.

## Création d'un contrôleur

Pour générer rapidement un nouveau contrôleur, utilisez la commande Artisan `make:controller`.
Tous les contrôleurs sont stockés par défaut dans `app/Http/Controllers`.

```shell theme={null}
php artisan make:controller UserController
```

## Contrôleur de base

Une classe de contrôleur peut avoir plusieurs méthodes publiques qui répondent aux requêtes HTTP entrantes.

```php theme={null}
<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Affiche le profil de l'utilisateur donné.
     */
    public function show(string $id): View
    {
        return view('user.profile', [
            'user' => User::findOrFail($id)
        ]);
    }
}
```

Une fois la classe et la méthode créées, vous définissez une route vers la méthode ainsi :

```php theme={null}
use App\Http\Controllers\UserController;

Route::get('/user/{id}', [UserController::class, 'show']);
```

Lorsque la requête entrante correspond à l'URI spécifié, la méthode `show` de la classe `App\Http\Controllers\UserController` est appelée avec les paramètres de route en argument.

<Info>
  Les contrôleurs n'ont pas besoin d'hériter d'une classe de base. Toutefois, il peut être utile d'hériter d'une classe de base commune contenant des méthodes partagées par tous les contrôleurs.
</Info>

## Contrôleurs à action unique

Si l'action d'un contrôleur est particulièrement complexe, il peut être pratique de dédier toute la classe à cette unique action.
Définissez pour cela une méthode `__invoke` dans le contrôleur.

```php theme={null}
<?php

namespace App\Http\Controllers;

class ProvisionServer extends Controller
{
    /**
     * Provisionne un nouveau serveur web.
     */
    public function __invoke()
    {
        // ...
    }
}
```

Pour enregistrer une route vers un contrôleur à action unique, il n'est pas nécessaire de préciser une méthode.
Passez simplement le nom du contrôleur au routeur.

```php theme={null}
use App\Http\Controllers\ProvisionServer;

Route::post('/server', ProvisionServer::class);
```

L'option `--invokable` de la commande Artisan `make:controller` génère un contrôleur invocable.

```shell theme={null}
php artisan make:controller ProvisionServer --invokable
```

## Contrôleurs de ressource

Si l'on considère chaque modèle Eloquent comme une « ressource », il est courant d'exécuter les mêmes opérations (CRUD) sur chacune.
Le routage de ressource Laravel affecte les routes typiques create / read / update / delete à un contrôleur en une seule ligne.

L'option `--resource` de la commande Artisan `make:controller` crée rapidement un contrôleur gérant ces actions.

```shell theme={null}
php artisan make:controller PhotoController --resource
```

Cette commande génère `app/Http/Controllers/PhotoController.php` avec un stub pour chaque opération de ressource.
Enregistrez ensuite une route de ressource pointant vers le contrôleur.

```php theme={null}
use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class);
```

Cette déclaration en une ligne crée plusieurs routes gérant diverses actions sur la ressource.
Le contrôleur généré contient déjà un stub pour chacune.

| Verbe HTTP | URI                    | Action  | Nom de la route |
| ---------- | ---------------------- | ------- | --------------- |
| GET        | `/photos`              | index   | photos.index    |
| GET        | `/photos/create`       | create  | photos.create   |
| POST       | `/photos`              | store   | photos.store    |
| GET        | `/photos/{photo}`      | show    | photos.show     |
| GET        | `/photos/{photo}/edit` | edit    | photos.edit     |
| PUT/PATCH  | `/photos/{photo}`      | update  | photos.update   |
| DELETE     | `/photos/{photo}`      | destroy | photos.destroy  |

<Info>
  La commande `php artisan route:list` affiche un aperçu rapide des routes de l'application.
</Info>

### Routes de ressource partielles

Lors de la déclaration d'une route de ressource, vous pouvez restreindre le sous-ensemble d'actions gérées par le contrôleur.

```php theme={null}
use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class)->only([
    'index', 'show'
]);

Route::resource('photos', PhotoController::class)->except([
    'create', 'store', 'update', 'destroy'
]);
```

### Routes de ressource API

Pour une API, on veut souvent exclure les routes qui affichent des templates HTML (`create`, `edit`).
La méthode `apiResource` exclut automatiquement ces deux routes.

```php theme={null}
use App\Http\Controllers\PhotoController;

Route::apiResource('photos', PhotoController::class);
```

## Injection de dépendances

### Injection dans le constructeur

Le conteneur de services Laravel est utilisé pour résoudre les dépendances de tous les contrôleurs.
Vous pouvez donc typer les dépendances requises dans le constructeur.
Elles seront résolues automatiquement et injectées dans l'instance.

```php theme={null}
<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * Crée une nouvelle instance de contrôleur.
     */
    public function __construct(
        protected UserRepository $users,
    ) {}
}
```

### Injection dans la méthode

En plus du constructeur, vous pouvez également typer des dépendances dans les méthodes.
Un cas courant est l'injection d'une instance `Illuminate\Http\Request`.

```php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * Enregistre un nouvel utilisateur.
     */
    public function store(Request $request): RedirectResponse
    {
        $name = $request->name;

        // Sauvegarde de l'utilisateur...

        return redirect('/users');
    }
}
```

Si la méthode reçoit également des paramètres de route, listez-les après les dépendances.
Par exemple, avec la route suivante :

```php theme={null}
use App\Http\Controllers\UserController;

Route::put('/user/{id}', [UserController::class, 'update']);
```

Définissez la méthode comme suit pour typer `Illuminate\Http\Request` tout en accédant au paramètre `id`.

```php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * Met à jour l'utilisateur donné.
     */
    public function update(Request $request, string $id): RedirectResponse
    {
        // Mise à jour de l'utilisateur...

        return redirect('/users');
    }
}
```

<Tip>
  L'injection de dépendances facilite l'injection de mocks lors des tests, améliorant la testabilité du code.
</Tip>

## Prochaines étapes

<Card title="Routage" icon="route" href="/fr/routing">
  Revenez sur la définition des routes et leur lien avec les contrôleurs.
</Card>


## Related topics

- [Routage](/fr/routing.md)
- [Autorisation (Gates et Policies)](/fr/authorization.md)
- [Présentation de Laravel Wayfinder](/fr/blog/wayfinder-introduction.md)
- [Introduction à Eloquent](/fr/eloquent.md)
- [Génération d'URL](/fr/urls.md)