Relationship Types

## Relations are methods In Eloquent a **relationship** is a public method on the model that returns a relation object, for example `HasMany` or `BelongsTo`. The method both describes the link and serves as a query builder for the related rows. The three basic types differ in one thing above all: **which table holds the foreign key**. | Declared on | Call | Foreign key lives on | Returns | |---|---|---|---| | `Student` | `$this->hasOne(StudentCard::class)` | `student_cards.student_id` | one model or `null` | | `Course` | `$this->hasMany(Lesson::class)` | `lessons.course_id` | a Collection | | `Lesson` | `$this->belongsTo(Course::class)` | `lessons.course_id` (its own table) | one model or `null` | Rule of thumb: the model whose table **carries** the key column says `belongsTo`; the model the key **points at** says `hasOne` or `hasMany`. ## How Eloquent guesses the keys The guesses come from different places for the two sides, which is where bugs hide. - **`hasOne` / `hasMany`** take the foreign-key name from the **parent class**: `getForeignKey()` returns the snake_case class basename plus `_` plus its key name, so `Course` gives `course_id`. The local key defaults to the parent's primary key. - **`belongsTo`** takes the foreign-key name from the **relationship method's name**: snake_case of the method plus `_` plus the related model's key name. A method named `course()` looks for `course_id`. - The owner key on `belongsTo` defaults to the related model's primary key. That second rule produces a classic surprise. A `Lesson` method named `module()` that returns `$this->belongsTo(Course::class)` looks for a `module_id` column, not `course_id`. Either name the method after the column or pass the key explicitly. ## Overriding the conventions Each method accepts the key names as extra arguments: ```php class Course extends Model { public function lessons(): HasMany { return $this->hasMany(Lesson::class, 'course_ref', 'code'); } } class Lesson extends Model { public function course(): BelongsTo { return $this->belongsTo(Course::class, 'course_ref', 'code'); } } ``` 1. `hasMany($related, $foreignKey, $localKey)` and `hasOne(...)` name the column on the **child** table, then the column on the parent it matches. 2. `belongsTo($related, $foreignKey, $ownerKey)` names the column on **this** table, then the column on the parent it points to. The two sides of one link must name the same pair of columns, just from opposite ends. ## Reading the result Accessed as a property, `$course->lessons` returns a Collection (empty when there are none), while `$lesson->course` and `$student->card` return a model or `null`. Calling the method, `$course->lessons()`, returns the relation object so you can add constraints before fetching. ## Handling the missing side A `belongsTo` or `hasOne` that finds nothing yields `null`, which breaks templates that chain on it. `withDefault()` returns an empty model instead, optionally pre-filled: ```php public function course(): BelongsTo { return $this->belongsTo(Course::class)->withDefault(['title' => 'Unassigned']); } ``` ## Common mistakes - Declaring `hasMany` on the model whose table holds the key; the relation then queries the wrong table. - Forgetting that `belongsTo`'s guess depends on the method name, not the class name. - Mismatched key types between the two columns, for example a string key on one side and an integer on the other. - Returning `hasOne` where the data allows many rows; Eloquent returns one of them without complaint. ## A worked check Given `students`, `student_cards` and `courses`/`lessons`, walk each declaration and ask which column it reads: 1. `Student::card()` returns `$this->hasOne(StudentCard::class)`: parent class `Student` gives `student_id`, looked up on `student_cards`. 2. `StudentCard::student()` returns `$this->belongsTo(Student::class)`: method name `student` gives `student_id`, read from the card's own row. 3. `Course::lessons()` returns `$this->hasMany(Lesson::class)`: `course_id` on `lessons`. 4. `Lesson::course()` returns `$this->belongsTo(Course::class)`: `course_id` on the lesson itself. Each pair names the same column from opposite ends, which is the property to verify in review. Declaring the return types, `HasOne`, `HasMany` and `BelongsTo`, also documents the direction for the next reader and lets static analysis catch a method that returns the wrong kind of relation.