In Eloquent, what do hasOneThrough() and hasManyThrough() declare, and which table does each of their key arguments refer to?

## What a through relation is Some links cross an intermediate model. A course has many lessons, and each lesson has many submissions; a teacher often wants "all submissions for this course" without looping over lessons. Eloquent's **through relations** declare that two-hop path once: - `hasManyThrough(Final::class, Intermediate::class)` returns **many** final models; - `hasOneThrough(Final::class, Intermediate::class)` returns **one** final model or `null`. ```php class Course extends Model { public function submissions(): HasManyThrough { return $this->hasManyThrough(Submission::class, Lesson::class); } } ``` The `submissions` table has no `course_id`. Eloquent resolves the relation in one query: 1. it selects from `submissions`; 2. it joins `lessons` on `lessons.id = submissions.lesson_id`; 3. it filters `lessons.course_id` to the course, or to every course when eager loading; 4. it adds `lessons.course_id` to the selected columns so eager-loaded results can be matched back to their course. ## The six arguments The key arguments are where people slip, because they alternate between the two tables: | Position | Name | Default for Course -> Lesson -> Submission | |---|---|---| | 1 | final model | `Submission::class` | | 2 | intermediate model | `Lesson::class` | | 3 | foreign key on the **intermediate** table | `course_id` (from the declaring model) | | 4 | foreign key on the **final** table | `lesson_id` (from the intermediate model) | | 5 | local key on the declaring table | `courses.id` | | 6 | local key on the intermediate table | `lessons.id` | So `hasManyThrough(Submission::class, Lesson::class, 'course_id', 'lesson_id', 'id', 'id')` spells out the defaults. ## The fluent form When both hops already exist as relations, `Course::lessons()` and `Lesson::submissions()`, you can compose them instead of repeating the keys: ```php public function submissions(): HasManyThrough { return $this->through('lessons')->has('submissions'); } ``` The dynamic spelling `$this->throughLessons()->hasSubmissions()` does the same. This form reuses the key names from the existing relations, so a custom key declared once is not restated, and it returns `hasManyThrough` when either hop is a has-many and `hasOneThrough` otherwise. ## `hasOneThrough` The same shape with single results: a student has one library card, and the card has one locker assignment, so `Student::hasOneThrough(LockerAssignment::class, LibraryCard::class)` returns the student's locker assignment or `null`. It is less common, but it answers "reach a single row two hops away" without loading the middle model. ## Limits - Both hops must be **has-type** links: the declaring model's key sits on the intermediate table, and the intermediate's key sits on the final table. A path that runs through a `belongsToMany` pivot is not a through relation. - The built-in through relations span exactly one intermediate model; longer chains need nested relations or a hand-written query. - The relation is **read-oriented**. You query and eager load it, but it does not fill in `lesson_id` for new rows, so submissions are created through `Lesson::submissions()`. ## Common mistakes - Swapping arguments 3 and 4, which makes the join compare the wrong columns and silently return nothing. - Declaring `hasManyThrough` when a real `belongsToMany` exists, or the reverse. - Using a through relation where the intermediate model's data is also needed; then load `lessons.submissions` instead so both levels are available. ## Through relation versus nested loading Two ways answer "a course's submissions", and they are not interchangeable: | | `$course->submissions` (through) | `$course->lessons` with each lesson's `submissions` | |---|---|---| | Result shape | one flat Collection of submissions | lessons, each holding its submissions | | Intermediate data | not returned | available | | Queries | one joined query | one for lessons, one for submissions when eager loaded | | Typical use | counts, lists, "all X for this Y" | pages grouped by the middle level | The through relation also works in the places any relation does: it can be eager loaded for many courses at once, constrained with extra `where` clauses on the final table, and counted. Soft-deleted intermediate rows are excluded when the intermediate model uses soft deletes, and `withTrashedParents()` includes them again.