Introduction à Eloquent

Qu’est-ce qu’Eloquent ORM

Laravel inclut Eloquent, un ORM (object-relational mapper). Eloquent facilite le dialogue avec la base et implémente le pattern ActiveRecord. Avec Eloquent, vous créez une classe « modèle » pour chaque table de la base. Le modèle permet de récupérer, insérer, mettre à jour et supprimer des enregistrements.

Avant d’utiliser Eloquent, configurez la connexion dans config/database.php. Par défaut, les variables DB_* du .env sont utilisées.

Créer un modèle

Utilisez la commande Artisan make:model.

php artisan make:model Post

Pour créer aussi une migration, utilisez -m.

php artisan make:model Post -m

Le modèle est créé dans app/Models.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    // ...
}

Correspondance modèle / table

Eloquent déduit le nom de la table à partir du nom de classe : snake_case au pluriel.

Modèle	Table
`Post`	`posts`
`User`	`users`
`AirTrafficController`	`air_traffic_controllers`

Si le nom ne suit pas cette convention, précisez $table explicitement.

class Post extends Model
{
    protected $table = 'blog_posts';
}

Timestamps

Par défaut, Eloquent gère automatiquement created_at et updated_at. Ajoutez $table->timestamps() à la migration pour bénéficier du remplissage automatique lors des enregistrements et mises à jour. Pour désactiver cette gestion automatique, mettez $timestamps à false.

class Post extends Model
{
    public $timestamps = false;
}

Protection contre l’assignation en masse

Pour utiliser les méthodes de création en masse, configurez la protection.

fillable

Indiquez les colonnes autorisées via $fillable.

class Post extends Model
{
    protected $fillable = [
        'user_id',
        'title',
        'body',
        'published',
    ];
}

guarded

À l’inverse, $guarded indique les colonnes interdites.

class Post extends Model
{
    // Seule la clé primaire est protégée, le reste est autorisé
    protected $guarded = ['id'];
}

Un $guarded vide autorise l’assignation de toutes les colonnes. Si vous passez directement des données utilisateur, des colonnes non prévues risquent d’être modifiées. Préférez lister explicitement les colonnes autorisées avec $fillable.

Flux d’exécution d’une requête Eloquent

Voici comment une requête telle que User::where()->get() est exécutée en interne.

CRUD de base

Lecture (Read)

Récupérer tous les enregistrements.

use App\Models\Post;

$posts = Post::all();

Avec conditions.

// Publications publiées
$publishedPosts = Post::where('published', true)->get();

// Premier résultat
$post = Post::where('published', true)->first();

// Par ID
$post = Post::find(1);

// 404 si absent
$post = Post::findOrFail(1);

Création (Create)

create insère un enregistrement (nécessite $fillable).

$post = Post::create([
    'title' => 'Première publication',
    'body' => 'Laravel est un excellent framework.',
    'published' => true,
]);

Vous pouvez aussi créer une instance et lui assigner les valeurs.

$post = new Post;
$post->title = 'Première publication';
$post->body = 'Laravel est un excellent framework.';
$post->save();

Mise à jour (Update)

Récupérez le modèle, modifiez-le, puis save.

$post = Post::find(1);
$post->title = 'Titre mis à jour';
$post->save();

update met à jour plusieurs colonnes en un appel.

Post::find(1)->update([
    'title' => 'Titre mis à jour',
    'published' => true,
]);

Mise à jour en masse selon un critère.

Post::where('published', false)->update(['published' => true]);

Recharger un modèle avec un verrou pessimiste

Pour recharger un modèle au sein d’une transaction tout en acquérant un verrou pessimiste, utilisez la méthode refreshForUpdate. Le modèle est rechargé avec un verrou FOR UPDATE.

use Illuminate\Support\Facades\DB;

DB::transaction(function () use ($post) {
    $post->refreshForUpdate();

    // Mettre à jour le modèle verrouillé...
});

Suppression (Delete)

$post = Post::find(1);
$post->delete();

Suppression directe par ID.

Post::destroy(1);

// Plusieurs IDs
Post::destroy([1, 2, 3]);

Méthodes de requête de base

Méthode	Description
`Post::all()`	Tous les enregistrements
`Post::find($id)`	Par ID (`null` si absent)
`Post::findOrFail($id)`	Par ID (404 si absent)
`Post::where('column', 'value')->get()`	Enregistrements correspondant à la condition
`Post::where('column', 'value')->first()`	Premier résultat correspondant
`Post::where('column', 'value')->count()`	Nombre de résultats
`Post::orderBy('created_at', 'desc')->get()`	Avec tri
`Post::latest()->get()`	Trie par `created_at` décroissant
`Post::limit(10)->get()`	Limite le nombre de résultats

Exemple : contrôleur manipulant le modèle Post

Exemple de contrôleur pour la table posts créée par une migration.

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class PostController extends Controller
{
    // Liste des publications
    public function index(): View
    {
        $posts = Post::where('published', true)
            ->latest()
            ->get();

        return view('posts.index', ['posts' => $posts]);
    }

    // Création
    public function store(Request $request): RedirectResponse
    {
        $validated = $request->validate([
            'title' => ['required', 'string', 'max:255'],
            'body' => ['required', 'string'],
            'published' => ['boolean'],
        ]);

        Post::create([
            ...$validated,
            'user_id' => $request->user()->id,
        ]);

        return redirect('/posts');
    }

    // Mise à jour
    public function update(Request $request, Post $post): RedirectResponse
    {
        $validated = $request->validate([
            'title' => ['required', 'string', 'max:255'],
            'body' => ['required', 'string'],
        ]);

        $post->update($validated);

        return redirect('/posts');
    }

    // Suppression
    public function destroy(Post $post): RedirectResponse
    {
        $post->delete();

        return redirect('/posts');
    }
}

Type-hinter Post $post dans une méthode de contrôleur active le route model binding : Laravel récupère automatiquement le modèle depuis le paramètre de route. Vous n’avez plus besoin d’écrire vous-même Post::findOrFail($id).

Cycle de vie des événements de modèle

Voici les événements déclenchés lors de save(). Ils diffèrent selon création ou mise à jour, mais saving et saved s’exécutent dans les deux cas.

Prochaines étapes

Migrations

Revoyez la création des tables utilisées par Eloquent via les migrations.

Pour commencer

Bases

Traitement des requêtes

Base de données

Authentification

Helpers et communication externe

Tests et déploiement

Assistance au développement IA

Qu’est-ce qu’Eloquent ORM

Créer un modèle

Correspondance modèle / table

Timestamps

Protection contre l’assignation en masse

fillable

guarded

Flux d’exécution d’une requête Eloquent

CRUD de base

Lecture (Read)

Création (Create)

Mise à jour (Update)

Recharger un modèle avec un verrou pessimiste

Suppression (Delete)

Méthodes de requête de base

Exemple : contrôleur manipulant le modèle Post

Cycle de vie des événements de modèle

Prochaines étapes

Migrations

​Qu’est-ce qu’Eloquent ORM

​Créer un modèle

​Correspondance modèle / table

​Timestamps

​Protection contre l’assignation en masse

​fillable

​guarded

​Flux d’exécution d’une requête Eloquent

​CRUD de base

​Lecture (Read)

​Création (Create)

​Mise à jour (Update)

​Recharger un modèle avec un verrou pessimiste

​Suppression (Delete)

​Méthodes de requête de base

​Exemple : contrôleur manipulant le modèle Post

​Cycle de vie des événements de modèle

​Prochaines étapes

Migrations

Qu’est-ce qu’Eloquent ORM

Créer un modèle

Correspondance modèle / table

Timestamps

Protection contre l’assignation en masse

fillable

guarded

Flux d’exécution d’une requête Eloquent

CRUD de base

Lecture (Read)

Création (Create)

Mise à jour (Update)

Recharger un modèle avec un verrou pessimiste

Suppression (Delete)

Méthodes de requête de base

Exemple : contrôleur manipulant le modèle Post

Cycle de vie des événements de modèle

Prochaines étapes