In Eloquent, how do you declare a many-to-many relation whose pivot table stores a grade, and when do you add a custom pivot with using()?

## Why a pivot table A student takes many courses and a course has many students. Neither table can hold the link in one column, so a **many-to-many** relation needs a third table, the **pivot** (intermediate) table, with one row per pairing. In Eloquent both ends are declared with `belongsToMany()`: ```php class Student extends Model { public function courses(): BelongsToMany { return $this->belongsToMany(Course::class) ->withPivot('grade', 'enrolled_on') ->withTimestamps() ->as('enrolment'); } } ``` `Course` declares the inverse with `belongsToMany(Student::class)`; the same table and key rules apply from the other side. ## The conventions - **Table name**: the two model names in snake_case, singular, sorted alphabetically and joined with `_`, so `Course` and `Student` give `course_student`. - **Pivot keys**: `student_id` for the declaring model and `course_id` for the related one, from each class's `getForeignKey()`. - Override them with `belongsToMany(Course::class, 'enrolments', 'student_id', 'course_id')`: related class, table, this model's key on the pivot, the related model's key on the pivot. Two further arguments name the parent and related key columns when they are not the primary keys. ## Extra columns on the pivot Each related model comes back with a **pivot attribute**, a small model holding the pivot row. By default it contains **only the two keys**. Everything else must be asked for: | Method | Effect | |---|---| | `withPivot('grade', 'enrolled_on')` | selects those pivot columns onto the pivot attribute | | `withTimestamps()` | maintains `created_at` and `updated_at` on the pivot; the table needs both columns | | `as('enrolment')` | renames the attribute from `pivot` to `enrolment` | | `using(Enrolment::class)` | hydrates the pivot row as your own class | Forgetting `withPivot('grade')` is the classic bug: `$course->pivot->grade` is simply `null` even though the column is filled. ## A custom pivot model with `using()` When the pivot row carries real meaning, such as an enrolment with a grade, give it its own class: ```php use Illuminate\Database\Eloquent\Relations\Pivot; class Enrolment extends Pivot { protected function casts(): array { return ['enrolled_on' => 'date']; } public function passed(): bool { return $this->grade !== null && $this->grade >= 50; } } ``` With `->using(Enrolment::class)`, `$course->enrolment` is an `Enrolment`, so casts, accessors and methods like `passed()` work on it. Points to know: - A custom pivot for a plain many-to-many extends `Pivot`; one for a polymorphic many-to-many extends `MorphPivot`. - `Pivot` sets `$incrementing = false`. If the pivot table has an auto-incrementing `id`, declare `#[Table(incrementing: true)]` or `public $incrementing = true` on the pivot class. - Pivot models may not use `SoftDeletes`; if enrolments must be soft deleted, promote the table to a full model. - `using()` does not replace `withPivot()`: the columns you want on the pivot still have to be listed. ## When to stop using a pivot If the pairing grows its own relations, such as submissions per enrolment, or is queried on its own, it is usually clearer to model it as a first-class `Enrolment` model with two `belongsTo` relations, and to reach the far side with `hasMany` or `hasManyThrough`. The pivot form stays best when the row is mainly a link with a few attributes. ## Declaration-time constraints Because the declaration returns a query builder, it can also fix a condition on the pivot for every use of that relation: - `wherePivot('status', 'active')` limits the relation to matching pivot rows when reading; - `withPivotValue('status', 'active')` both filters on that value and writes it when rows are attached through the relation; - `orderByPivot('enrolled_on')` orders the related models by a pivot column. A common pattern is two relations over one pivot, such as `courses()` and `activeCourses()`, where the second adds `wherePivot('status', 'active')`. The steps to set up a graded enrolment are therefore: 1. choose the pivot table name, conventional or explicit; 2. list every extra column with `withPivot()` and add `withTimestamps()` if the table has both timestamp columns; 3. add `as()` for a readable accessor and `using()` when the row needs casts or methods; 4. mirror the declaration on the inverse model so both sides agree.