Querying & Syncing Relations

## Two spellings, two different things An Eloquent relation is declared as a method on the model: ```php public function tags(): BelongsToMany { return $this->belongsToMany(Tag::class); } ``` That single method can be reached in two ways, and they return different things. | Expression | What you get | When SQL runs | |---|---|---| | `$photo->tags()` | A `BelongsToMany` **relation object**, a query builder scoped to this photo | Only on a terminal call (`get()`, `count()`, `first()`, `exists()`, `pluck()`), and **again on every** such call | | `$photo->tags` | The **results**: an Eloquent `Collection` of `Tag` models (for to-one relations, a model or `null`) | Once, on first access if not already loaded; later reads reuse the cached value | ## How the property form works A model has no real `tags` property. Reading `$photo->tags` falls through to the model's attribute lookup. In outline, the framework's `getRelationValue()` then does this: 1. If the relation is already in the model's loaded relations, return it without querying. 2. If `tags` is not a relation method, return `null`. 3. Otherwise call `tags()`, run the relation query, store the result on the model with `setRelation()`, and return it. Step 3 means the **first** read queries and every later read on the same model instance is free. It also means the value is a **snapshot**: after `$photo->tags()->attach(9)`, an already-loaded `$photo->tags` does not contain tag 9 until the relation is reloaded. If the relation method forgets its `return`, the property form throws a `LogicException` saying the method must return a relationship instance. ## How the method form works `$photo->tags()` builds a fresh relation object every time you call it. It behaves like a query builder with the join and the `photo_id` constraint already applied, so you can keep chaining: - `$photo->tags()->where('slug', 'like', 'sun%')->get()` filters in SQL and returns only the matching tags. - `$photo->tags()->orderBy('name')->pluck('name')` reads one column. - `$photo->tags()->exists()` asks the database a yes/no question. None of this touches the cached `tags` value on the model. ## Where the difference matters - **Counting.** `$photo->tags()->count()` sends a `COUNT` query. `$photo->tags->count()` loads every tag row and counts the collection in PHP. With five tags nobody notices; with fifty thousand likes on a popular photo, the second loads fifty thousand models. If the collection is **already loaded**, though, counting it in PHP costs nothing. - **Filtering.** `$photo->tags()->where(...)` filters in the database. `$photo->tags->where(...)` is a `Collection` method that filters rows already in memory — correct, but only after loading all of them. - **Writing.** Every write goes through the method: `$photo->tags()->attach()`, `sync()`, `detach()`, `$photo->album()->associate()`, `$album->photos()->create([...])`. The property is a plain collection or model; it has no `attach()`. - **Repeated reads.** In a Blade view that prints `$photo->tags` three times, the property form queries once. Writing `$photo->tags()->get()` three times queries three times. ## The rule to remember Use the **property** when you want the related records and are happy for them to be cached on this model. Use the **method** when you want to add constraints, ask an aggregate question in SQL, or write through the relation. Loading relations for many parents at once is a separate subject (eager loading), and so is making lazy property reads fail in development. ## Inspecting and resetting the cache The cached value lives in the model's relations array, and a few public methods work with it directly: - `$photo->relationLoaded('tags')` returns `true` once the property has been read (or the relation was loaded some other way), which is handy in a view that should not trigger a query. - `$photo->setRelation('tags', $collection)` stores a value you already have, so a later `$photo->tags` returns it without SQL. - `$photo->unsetRelation('tags')` forgets the cached value; the next property read queries again. This is the cheapest way to make a stale relation fresh after a write. ## A worked example On a photo detail page: 1. `$photo->tags` in the header runs one query and caches five tags. 2. `$photo->tags` in the sidebar costs nothing. 3. `$photo->tags()->where('featured', true)->get()` in the footer runs a new, filtered query and does **not** replace the cached five. 4. `$photo->tags()->attach($newTagId)` writes a pivot row; the cached collection still has five tags until you unset or reload it.